Чи є якісь емпіричні дослідження щодо впливу коментування вихідного коду на якість програмного забезпечення, ремонтопридатність та продуктивність розробників? [зачинено]

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

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

• Якщо фрагмент коду добре написаний, він пояснює себе, тому коментувати його не потрібно
• Якщо фрагмент коду не є роз'яснювальним, тоді переробляйте його та зробіть його зрозумілим, щоб він не потребував коментарів
• Ваш тестовий набір - це ваша жива документація
• З часом код і коментарі виходять із синхронізації, і це стає ще одним джерелом головних болів
• Agile каже, що робочий код важливіший за купу документації, тому ми можемо сміливо ігнорувати написання коментарів

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

Знову ж таки, API Java, API какао, Android API тощо показують, що якщо ви хочете написати та підтримувати якісну документацію, це можливо.

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

Як такий, я шукаю наукові праці та емпіричні дослідження щодо впливу програмної документації, особливо коментування вихідного коду, на її якість та ремонтопридатність, а також на їх вплив на продуктивність команди.

Чи натрапили ви на такі статті, і який результат був від них, якщо вони є?

У "Ефект модуляризації та коментарів на розуміння програми" (1981) Вудфілд, Дансмор та Шен виявили, що "суб'єкти, програми яких містили коментарі, могли відповісти на більше запитань, ніж ті, без коментарів".

Однак, в "Навчання метриці для читабельності коду" (2010), Реймонд PL Buse та Westley Weimer виявили, що коментарі мають лише обмежений вплив на читабельність та якість:

З реферату:

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

З сторінки 12:

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

Майте на увазі, що прихильники "кодування без коментування" не кажуть, що код без коментарів краще, ніж код з коментарями. Вони стверджують, що конкретний стиль коду без коментарів - той, який витягує код в методи із самоописуючими іменами, той, що вводить пояснювальні змінні , той, що має гарний тестовий набір, - краще, ніж код, який не робить цього але є коментарі. Це може ускладнити застосування будь-яких досліджень, які були зроблені.