Чи застарілі коментарі міський міф?

Я постійно бачу людей, які заявляють, що "коментарі, як правило, застаріли". Річ у тому, що я думаю, що я бачив, можливо, два чи три застарілі коментарі за всю мою кар’єру. Застаріла інформація в окремих документах трапляється постійно, але, на мій досвід, застарілі коментарі в самому коді надзвичайно рідкісні.

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

Постійно

Я дійсно не можу повірити, що я єдиний, хто плаває у застарілих та оманливих коментарях. За випадковості це допомагає зрозуміти:

Це, мабуть, найголовніше залежить від віку коду. Наступним фактором буде плинність кадрів.

Я виконую рівні роботи з НДДКР та технічного обслуговування. Науково-дослідна робота - це новий код, як правило, це дещо поза увагою. Багато моїх колег вірять, що вони дають багато коментованих пояснень, коли намагаються щось, для чого вже немає бібліотеки. Оскільки співвідношення коментарів до коду вище звичайного, просто більше можливостей не синхронізуватися.

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

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

Конкретні приклади:

• Коментарі, що описують поліпшення продуктивності для певної методології, наприклад, уникання копії в пам'яті. Велика справа, коли верхня машина в Pentium 2 з МБ оперативної пам’яті, але навряд чи зараз це проблема.

• TODO

• Блоки кодованого коду, включаючи коментарі. Коментар, можливо, мав сенс у його початковому місці, але навряд чи має сенс тут

• Блоки коментування зверху коментованого коду (Хто знає, скільки років там було).

У всьому цьому ви бачите тенденцію просто не підтримувати коментарі та код на тому ж рівні, що і програмне забезпечення. ІДЕ та основні звички розробника не допомагають у цьому, моє око було навчене пройти повз них. Я думаю, що застарілі коментарі відносно дешеві, яких можна уникати в екологічному просторі та активних проектах. Якщо ви можете підтримувати співвідношення код / ​​коментар на високому рівні, це не так важливо, щоб підтримувати їх у курсі. Трохи важче виправдати полювання на ці речі, коли ви плануєте х годин для виправлення помилок у виробничій системі.

"коментарі, як правило, застаріли."

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

Річ у тому, що я думаю, що я бачив, можливо, два чи три застарілі коментарі за всю мою кар’єру.

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

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

Недавнє дослідження Roehm et al. 2012 рік зазначає:

21 учасник [з 28] повідомив, що вони отримують свою основну інформацію з вихідного коду та вбудованих коментарів, тоді як лише четверо заявили, що документація є їх основним джерелом інформації.

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

_{Roehm, T., Tiarks, R., Koschke, R., & Maalej, W. (2012, червень). Як професійні розробники розуміють програмне забезпечення ?. У працях Міжнародної конференції з інженерії програмного забезпечення 2012 року (с. 255-265). IEEE Press.}

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

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

Коментарі - як тести, вони дуже хороші, коли вони актуальні, але можуть ще важче зрозуміти код, якщо таких немає.

Якщо ви ніколи не бачили застарілих коментарів, вам дуже пощастило.

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

Застарілі коментарі часто з'являються в JavaDoc:

• Перелічуючи аргументи, яких більше не існує
• Не пояснюючи всіх аргументів (відсутні, мабуть, були додані пізніше)
• Подібні речі за винятками тощо.

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

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

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

featureList = GetFeatures();

// Sorting features and deleting empty ones from the list...
ProcessFeatures(featureList);

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

Запитайте себе в цьому. Ви коли-небудь змінювали рядок коду і не змінювали пов'язані коментарі чи додавали нові?

Я працював із багатьма застарілими кодами, і коментарі іноді навіть не є близькими до релевантних.

Здебільшого мій досвід відповідає вашому, але я зіткнувся з одним випадком, коли це було правдою по всій базі коду. Це було додаток, яке було написано роками раніше консалтинговим магазином, який більше не був «на доброму рівні» з клієнтом.

Компанія зробила надзвичайну роботу, коментуючи код, але програмісти, які підтримували його з моменту оригінальної передачі, були частиною мислення «лише змінити те, що абсолютно потрібно змінити», що саме по собі є непоганим. На жаль, вони дотримувалися такого ж ставлення до коментарів, що призводило до досить великого розриву між коментарями та кодом з часом.

Я не бачу занадто багато описових коментарів, які застаріли, але я бачу безліч коментарів TODO, які існують роками. Я б хотів, щоб вони були як капсули часу, і сказав щось подібне:

//TODO: In 15 years AND NO SOONER... actually implement this method.

Останні 3 проекти, над якими я працював, я витратив кілька днів на те, щоб видалити застарілі, оманливі та просто непотрібні коментарі з кодової бази. Там, де це можливо і необхідно, я замінюю їх на більш відповідні коментарі, але частіше за все це лише питання про видалення коментаря та продовження роботи.

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

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

Вам потрібно покластися лише на один поганий коментар, щоб зіпсувати великий додаток і витратити багато часу.

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