Комментировать сейчас проще, чем когда-либо. В Java есть несколько хороших методов для привязки комментариев к классам, и Java IDE хороши для создания оболочек комментариев для вас. Такие языки, как Clojure, даже позволяют вам добавить описание функции в сам код функции в качестве аргумента.
Однако мы все еще живем в эпоху, когда хорошие разработчики часто пишут устаревшие или плохие комментарии - я заинтересован в повышении надежности и полезности моих комментариев.
В частности, я заинтересован в Java / Clojure / Python, но ответы не обязательно должны зависеть от языка.
Существуют ли какие-либо новые методы, которые проверяют комментарии и автоматически обнаруживают либо «неубедительные» комментарии (например, комментарии с магическими числами, неполные предложения и т. Д.), Либо неправильные комментарии (например, обнаружение неправильно введенных переменных или тому подобное).
И что еще более важно: существуют ли принятые «политики комментирования» или стратегии? Существует множество советов о том, как писать код, но как насчет «как комментировать»?
Это может быть спорным, но мой совет - написать как можно меньше комментариев. Вместо этого используйте красивые, понятные имена классов, имен переменных и методов. Напишите свой код наиболее понятным способом; и считайте это самым важным атрибутом вашего кода (кроме того, что он соответствует его требованиям). Оставляйте комментарии только в том случае, если вы сделали метод настолько ясным, насколько это возможно, и все же считаете, что он требует дополнительных пояснений.
И имейте организационную практику, что, когда кто-либо меняет класс каким-либо образом, он должен убедиться, что комментарии все еще верны.
источник
if (a == b) then c();делает, но если я не знаю , почему он это делает - что, когда комментарий должен быть использован :)Я не уверен насчет других языков, но python позволяет вам писать тесты, которые являются формой самопроверяющихся комментариев. Конечно, их не следует использовать вместо реального модульного тестирования, но это быстрый и простой способ документирования конкретных функций, которые могут быть не такими очевидными, как следовало бы. Они имеют дополнительное преимущество, заключающееся в том, что они могут выполнять тесты комментариев, чтобы убедиться, что комментарии все еще верны (по крайней мере, часть из них, которые содержат тесты).
источник
Одно из самых авторитетных мест, где можно найти, как использовать комментарии к коду для автоматической генерации документации, - это, безусловно, doxygen . Хотя могло бы быть больше таких инструментов.
Это определяет стандарт написания комментариев, который следует соблюдать для автоматической генерации документации. Тем не менее, это дает больше структуры, но не проверяет семантически; например, он не может проверить, использовали ли вы вводящий в заблуждение английский для описания назначения функции!
Хотя это лучшее, что позволяет структурировать комментарии, лично я считаю, что для того, чтобы сделать код более понятным, нужно больше документации. Некоторое время назад в P.SE возник вопрос: может ли код быть документацией в инструментах разработчика с открытым исходным кодом? Как часто это? Конечно, это относится и к проектам с открытым исходным кодом.
Чтобы сделать код более понятным - практически более важно, чтобы существовала внешняя документация, которая помогает создать структуру обработки кода, и тогда комментарии внутри кода должны быть ограничены, чтобы их можно было увидеть.
Я думаю, что если вы хотите определить политику для написания комментариев, вы должны включить в него целостный подход, включенный в стандарт кодирования. Посмотрите это: Какие могут быть некоторые подводные камни при внедрении руководства по стилю и программного обеспечения для генерации документации в команде разработчиков?
Обычно комментарии составляют менее 5% кода. И на практике, в то время как сами обзоры кода привлекают гораздо меньше внимания (по сравнению с другими аспектами разработки), практически также сложно анализировать комментарии.
источник
Существует хорошо известная методика - она называется «обзор кода» и имеет сестру по имени «парное программирование». Не ожидайте ничего "автоматически" здесь.
«Код завершен» содержит не только все о том, как кодировать, но и главы о том, «как комментировать», особенно о том, как написать самодокументированный код.
источник
Для Java один из источников, который мне понравился, - « Как писать комментарии к документу для инструмента Javadoc» :
И пункт 44: написать комментарии к документу для всех открытых элементов API :
из эффективной Java 2-е издание .
источник