Должны ли вы документировать все или только большинство?

Кажется немного спорным предметом документирования всего, включая синтаксис «JavaBean» методов получения и установки полей: люди говорят, что это бесполезно длинный и повторяющийся разрыв DRY (не повторяйте себя) , что соглашение об именах должно объяснять все , и это загромождает код / ​​документацию. Иногда эти аргументы работают. Но в других случаях вы в конечном итоге с этим:

Выше часто встречаются проекты с открытым исходным кодом, которые смело следуют этим принципам. Вы остались с совершенно бесполезной документацией . Это ничего не объясняет о том, что происходит внизу, о возможных эффектах или даже о том, каково ожидаемое значение (может ли оно быть нулевым или никогда нулевым? Я не знаю; Javadoc не сообщает мне).

Итак, когда я должен документировать? Должен ли я документировать все, даже если это иногда загромождает код? Или я ничего не документирую, потому что в моих глазах это "очевидно"?

Документируйте все, что имеет смысл документировать .

В идеальном мире, да, вы бы документировали все. Тем не менее, на Земле у нас есть крайние сроки, специальные мероприятия, посещение семей и друзей, каникулы - всего 24 часа в день и только 365 дней в году. Просто не хватает времени документировать все. Итак, оптимально, документируйте все, что вы можете (вы не сделаете), но получите максимальную отдачу от ваших денег:

• Сделайте код читабельным и сигнатуры методов настолько очевидными, насколько это возможно, чтобы меньше было необходимости в документировании.
• Сначала документируем самые непонятные вещи. Помогайте другим, документируя сумасшедшие взломы, которые вы должны были сделать, чтобы вывести вещи за дверь.
• Документируйте, почему, прежде чем что - не комментируйте, что что-то делает, например, «Перебирайте записи клиентов, где баланс меньше нуля, а рейтинг меньше единицы, и добавляйте их в список exemptCustomers». Документируйте, почему вы добавляете их в список простым английским языком (или языком вашей команды), например: «Поскольку у этих клиентов отрицательный баланс и низкие рейтинги, они заставляют нас терять деньги, поэтому лишите их возможности проверить.

Продолжайте документирование, пока не увидите, как кто-то другой прочитает его, не чувствуя необходимости что-либо объяснять

На прошлой неделе в The Daily WTF была замечательная статья о документации. Я думаю, это говорит обо всем, поэтому я просто оставлю ссылку:

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

По сути, это говорит о том, что вы не должны документировать что-либо, если это не будет полезно (некоторая документация просто сгниет в ящике), и документировать наименьшее количество информации, которая необходима для понимания определенной части проекта. Слишком много документации просто смущает читателя.

Действительно зависит от того, насколько читаемый код читающей его аудитории. Выясните, кто является аудиторией для чтения вашего кода, и попросите кого-нибудь, кто соответствует этому профилю, прочитать ваш код.

Другой подход заключается в том, чтобы через неделю пересмотреть свой собственный код и посмотреть, понимаете ли вы, что вы сделали, если нет, документировать его и просмотреть код примерно через две недели.

Хотя я ценю четкую и обширную документацию, нет ничего лучше, чем самодокументированный код. Итак, суть (для меня):

Быть очень подозрительным к (исходному коду) документации; попробуйте сделать его избыточным за счет улучшения кода, но не избегайте четкого и полного документирования при необходимости.

Конечно, при определенных обстоятельствах документация может потребоваться по причинам, отличным от «объяснения того, что делает код» (например: большая команда, стандарты организации и т. Д. И т. Д.).

Мое предложение по документации заключается в том, что если в коде есть что-то причудливое, это относится к документу, который следует обновлять. Мне кажется, что мне приходится много толковать, когда что-то делается определенным образом, что может иметь побочные эффекты, которые следует отметить, например, что-то может быть сделано для рекурсивной проверки того, что элементы внука обрабатываются при прохождении дерева узлов провести какой-то тест на всех потомках. Изложение причин, по которым что-то было сделано определенным образом, может быть хорошим способом узнать, была ли веская причина использовать что-либо.

Проще говоря, документация призвана помочь разработчикам сейчас, а сопровождающим - в будущем.

Если вы помните этот простой принцип, то уровень документации должен быть самоопределяющимся.

Документация ради документации - пустая трата времени ... но объяснение того, что вы делаете сегодня, более полезно, чем то, что кому-то придется перепроектировать ваш код через пять лет.

Лично я иду с подходом рассмотреть документирование всего. Т.е. при кодировании я в каждой точке считаю, будет ли документ полезен. В большинстве случаев ответ «да» касается именно тех ограничений и областей знаний, которые упоминаются в первоначальном вопросе. Например, нулевая способность, уникальные ограничения, интерпретация поля в более широкой области.

Чтобы избежать дублирования, я стараюсь задокументировать основные классы API с такой информацией. Тогда только документируйте реализации и внутренности, где есть неочевидное или противоречивое поведение. Я считаю, что это хорошо работает, так как пользователям API нужна большая помощь и документация. Обычно можно предположить, что люди, изменяющие реализацию, знают API, поэтому имейте это в виду.

Я также склонен документировать только получателей. Я не дублирую документацию на сеттеры, определения полей и параметры конструктора. Я только документирую неочевидное поведение, такое как настройки по умолчанию в этих местах. Любое поведение, которое может быть выведено из документации получателя, не задокументировано. Например, если получатель задокументирован как никогда не возвращающий ноль, я обычно не документирую, что вы не можете передать ноль в установщик, если нет значения по умолчанию.

Некоторым людям нравится отмечать этот акт «рассмотрения документации», добавляя пустые комментарии, где они рассмотрели документацию, но сочли это ненужным. Мне не нравится эта практика, поскольку она просто загромождает код и мешает.