Я сторонник комментирования исходного кода и документирования программных продуктов. Мой личный опыт и наблюдения показывают, что работа над исходным кодом, который тщательно комментируется, помогает мне по-разному, когда мне приходится разрабатывать программное обеспечение или поддерживать его.
Однако есть еще один лагерь, который говорит, что комментировать в конечном итоге бесполезно или его ценность сомнительна. Многочисленные сторонники кодирования без комментариев утверждают, что:
- Если фрагмент кода написан хорошо, это говорит само за себя и, следовательно, не нуждается в комментировании
- Если фрагмент кода не требует пояснений, то реорганизуйте его и сделайте его понятным, чтобы он не нуждался в комментариях
- Ваш набор тестов - это ваша живая документация
- Со временем код и комментарии перестают синхронизироваться, и это становится еще одним источником головной боли
- Agile говорит, что рабочий код важнее куч документации, поэтому мы можем спокойно игнорировать написание комментариев
Для меня это просто догма. Опять же, я лично заметил, что программное обеспечение, написанное командами умных и опытных разработчиков, в конечном итоге приводит к значительному объему кода, который не требует пояснений.
Опять же, Java API, Cocoa API, Android API и т. Д. Показывают, что если вы хотите писать и поддерживать качественную документацию, это возможно.
Сказав все это, разговоры о плюсах и минусах документации и комментарии к исходному коду, основанные на личных убеждениях, обычно не заканчиваются хорошо и не приводят к удовлетворительным выводам.
Поэтому я ищу научные статьи и эмпирические исследования о влиянии программной документации, особенно комментируя исходный код, на его качество и удобство обслуживания, а также его влияние на производительность команды.
Сталкивались ли вы с такими статьями и каков был их итог, если таковые имеются?