Существуют ли какие-либо эмпирические исследования о влиянии комментирования исходного кода на качество программного обеспечения, удобство обслуживания и производительность разработчика? [закрыто]

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

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

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

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

Опять же, Java API, Cocoa API, Android API и т. Д. Показывают, что если вы хотите писать и поддерживать качественную документацию, это возможно.

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

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

Сталкивались ли вы с такими статьями и каков был их итог, если таковые имеются?

В «Влияние модульности и комментариев на понимание программ» (1981) Вудфилд, Дансмор и Шен обнаружили, что «субъекты, программы которых содержали комментарии, могли ответить на большее количество вопросов, чем те, у которых нет комментариев».

Однако в «Изучении метрики для читабельности кода» (2010) Рэймонд П. Л. Бузе и Уэстли Ваймер обнаружили, что комментарии имеют ограниченное влияние на читабельность и качество:

Из аннотации:

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

Со страницы 12:

Мы обнаружили, что комментарии были лишь умеренно хорошо коррелированы с понятием читаемости наших комментаторов (33% относительной мощности). Одним из выводов может быть то, что, хотя комментарии могут улучшить читабельность, они обычно используются в сегментах кода, которые начинались менее читаемыми: комментарий и нечитаемый код эффективно уравновешиваются. В итоге может показаться, что комментарии не всегда сами по себе указывают на высокую или низкую читаемость.

Имейте в виду, что сторонники «кодирования без комментариев» не говорят, что код без комментариев лучше, чем код с комментариями. Они утверждают, что определенный стиль кода без комментариев - тот, который извлекает код в методы с самоописывающимися именами, тот, который вводит объясняющие переменные , тот, у которого есть хороший набор тестов - лучше, чем код, который не делает эти вещи но есть комментарии. Это может осложнить применимость любых исследований, которые были сделаны.