Самодокументирующийся код

Внешняя документация

• трекер задач/багов (JIRA..)
• wiki
• отдел тех. писателей

Стиль программирования как вид документации

Внутренняя документация сильнее связана с кодом, поэтому при изменении кода она чаще остается корректной

• Грамотное структурирование программы
• Использование простых и понятных подходов
• Удачный выбор имен переменных и методов

Стиль программирования как вид документации

Внутренняя документация сильнее связана с кодом, поэтому при изменении кода она чаще остается корректной

• Использование именованных констант вместо литералов
• Ясное форматирование
• Минимизация сложности потока управления и структур данных

комментировать или не комментировать?

1. Комментарии легче написать плохо, а не хорошо, и комментирование иногда бывает скорее вредным, чем полезным.
2. - Нужно следить за актуальностью
3. + Описание кода на высоком уровне абстракции

Исмена:

- Мне кажется, что люди, отказывающтеся писать комментарии,

1. Думаю, что их код понятнее, чем мог бы быть
2. считают, что другие программисты гораздо сильнее интересуются их кодом, чем есть на самом деле
3. думают, что другие программисты умнее, чем есть на самом деле
4. ленятся
5. боятся, что кто-то другой узнает как работает их код

Style guide

• делайте в комментарии такой же отступ как и в соответствующем ему коде
• отделяйте каждый комментарий хотя бы одной пустой строкой

Виды комментариев

• Повторение кода
• Объяснение кода
• Маркер в коде
• Резюме кода
• Описание цели кода
• Информация, которую невозможно выразить в форме кода

Эффективные комментарии

• Комментарии должно быть легко поддерживать
• Используйте линтеры
• .. и jsdoc

Методики комментирования

• Комментирование отдельных строк
• Комментарии в концах строк и связанные с ними проблемы
• Комментирование абзацев кода

Советы

• Во время документирования сосредоточьтесь на самом коде
• Придумывая комментарий абзаца, страмитесь ответить на вопрос "почему?", а не "как?"
• Используйте комментарии для подготовки читателя дока к последующемй информации

Советы

• Не размножайте комментарии без необходимости
• Документируйте сюрпризы
• Избегайте сокращений

Советы

• Проведите различия между общими и детальными комментариями
• Комментируйте все, что имеет отношение к ошибкам или недокументированным возможностям языка или среды
• Обосновывайте нарушения хорошего стиля программирования

Советы

• Не комментируйте хитрый код - перепишите его
• Указывайте в комментациях единицы измерения численных величин
• Указывайте в комментариях диапазоны допустимых значений численных величин

Советы

• Комментируйте смысл закодированных значений
• Комментируйте ограничение входных данных
• Включайте в комментарий, относящийся к переменной, имя переменной

Ключевый моменты

• При плохом выполнении комментирование является пустой тратой времени и иногда причиняет вред
• При грамотном применении комментирование полезно
• Основная часть критически важной информации о программе должна содержаться в исходном коде.

Ключевый моменты

• Хороший код сам является самой лучшей документацией
• Комментарии должны сообщать о коде что-то такое, что он не может сообщить сам - на уровне резюме или уровне цели
• Используйте стиль, который было бы легко поддерживать

Спасибо! Вопросы?