Лучшие практики в написании комментариев и документации

20

Комментировать сейчас проще, чем когда-либо. В Java есть несколько хороших методов для привязки комментариев к классам, и Java IDE хороши для создания оболочек комментариев для вас. Такие языки, как Clojure, даже позволяют вам добавить описание функции в сам код функции в качестве аргумента.

Однако мы все еще живем в эпоху, когда хорошие разработчики часто пишут устаревшие или плохие комментарии - я заинтересован в повышении надежности и полезности моих комментариев.

В частности, я заинтересован в Java / Clojure / Python, но ответы не обязательно должны зависеть от языка.

Существуют ли какие-либо новые методы, которые проверяют комментарии и автоматически обнаруживают либо «неубедительные» комментарии (например, комментарии с магическими числами, неполные предложения и т. Д.), Либо неправильные комментарии (например, обнаружение неправильно введенных переменных или тому подобное).

И что еще более важно: существуют ли принятые «политики комментирования» или стратегии? Существует множество советов о том, как писать код, но как насчет «как комментировать»?

— jayunit100
источник

40

Имена / документация должны рассказать вам, что вы делаете.
Реализация должна рассказать вам, как вы это делаете.
Комментарии должны сказать вам, почему вы делаете это так, как вы делаете.

— чокнутый урод
источник

6

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

2

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

— Даллин

2

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

— фрик с трещоткой

@dallin: «Это миф, что вы можете написать весь код достаточно ясно, чтобы любой программист мог понять его с первого взгляда», - хотел бы поговорить с вами дядя Боб. - «Мне не нужно называть эту функцию описательно, потому что любой может просто прочитать код в функции, чтобы увидеть, что она делает». Дать хорошие и ясные имена переменным и методам - это именно то, как программисты должны четко понимать, что их код делается!

— Клар

14

Это может быть спорным, но мой совет - написать как можно меньше комментариев. Вместо этого используйте красивые, понятные имена классов, имен переменных и методов. Напишите свой код наиболее понятным способом; и считайте это самым важным атрибутом вашего кода (кроме того, что он соответствует его требованиям). Оставляйте комментарии только в том случае, если вы сделали метод настолько ясным, насколько это возможно, и все же считаете, что он требует дополнительных пояснений.

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

— Дауд говорит восстановить Монику
источник

1

Это хорошее начало, но я думаю, что для удовлетворения вопроса ОП вам нужно написать что-то, что отвечает его актуальным опасениям в отношении автоматической проверки.

— Роберт Харви

2

+1 - я также думаю, что комментарии должны использоваться только для объяснения того, почему код был написан. Я знаю , что if (a == b) then c();делает, но если я не знаю , почему он это делает - что, когда комментарий должен быть использован :)

— Deco

Деку - я полностью согласен. Комментарии хороши, когда я хочу понять, как конкретный метод вписывается в процесс в целом. Другими словами, ПОЧЕМУ вы вызываете этот метод, или ПОЧЕМУ он делает то, что делает.

— Дауд говорит восстановить Монику

Помимо ясности написанного кода, мы также должны сохранять идеи (мысли на уровне кода), мысли и т. Д., Используя комментарии TODO. Например, если вы видите, что функция / класс способна правильно обрабатывать текущий размер данных, но потенциально не сможет справиться с нагрузкой через 2 года, то обязательно напишите свое наблюдение, используя комментарий TODO. Будущие разработчики действительно оценят ваши усилия. Никогда не пытайтесь записывать эти вещи в отдельном текстовом документе, пока пишете код, никто не ссылается на такие документы.

— TechCoze

см. также: «Комментарии - это запах кода»

— комнат

5

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

— Джош Смитон
источник

1

И Sphinx сравнивает код с документацией, чтобы обеспечить показатели покрытия.

— С.Лотт

3

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

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

Хотя это лучшее, что позволяет структурировать комментарии, лично я считаю, что для того, чтобы сделать код более понятным, нужно больше документации. Некоторое время назад в P.SE возник вопрос: может ли код быть документацией в инструментах разработчика с открытым исходным кодом? Как часто это? Конечно, это относится и к проектам с открытым исходным кодом.

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

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

Обычно комментарии составляют менее 5% кода. И на практике, в то время как сами обзоры кода привлекают гораздо меньше внимания (по сравнению с другими аспектами разработки), практически также сложно анализировать комментарии.

— Дипан Мехта
источник

1

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

— Дауд говорит восстановить Монику

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

— DanMan

2

Существуют ли какие-либо новые методы, которые проверяют комментарии и автоматически обнаруживают либо «неубедительные» комментарии (например, комментарии с магическими числами, неполные предложения и т. Д.), Либо неправильные комментарии (например, обнаружение неправильно введенных переменных или тому подобное).

Существует хорошо известная методика - она называется «обзор кода» и имеет сестру по имени «парное программирование». Не ожидайте ничего "автоматически" здесь.

И что еще более важно: существуют ли принятые «политики комментирования» или стратегии? Есть много советов о том, как кодировать --- но как насчет "как комментировать?"

«Код завершен» содержит не только все о том, как кодировать, но и главы о том, «как комментировать», особенно о том, как написать самодокументированный код.

— Док Браун
источник

+1 для завершения кода. У «Чистого кода» Роберта Мартина также есть хорошая глава по написанию полезных рекомендаций. Я не уверен в мире Java, но в мире .NET у нас есть Resharper, который может «автоматически» проверять ссылки на элементы кода в комментариях :)

— MattDavey

0

Для Java один из источников, который мне понравился, - « Как писать комментарии к документу для инструмента Javadoc» :

В этом документе описываются руководство по стилю, обозначения тегов и изображений, которые мы используем в комментариях к документации для программ Java, написанных на Java Software, Sun Microsystems.

И пункт 44: написать комментарии к документу для всех открытых элементов API :

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

из эффективной Java 2-е издание .

— EGHM
источник