Чи може коментований код бути цінною документацією?

Я написав наступний код:

if (boutique == null) {
    boutique = new Boutique();

    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.persist(boutique);
} else {
    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    //boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.merge(boutique);
}

Тут є коментований рядок. Але я думаю, що це робить код більш зрозумілим, роблячи очевидним, в чому різниця між ifі else. Різниця ще більш помітна в кольоровій підсвічуванні.

Чи можна коментувати подібний код колись корисною ідеєю?

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

По-перше, коментований код не складається. Це очевидно, але це означає, що:

1. Код може навіть не працювати.

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

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

По-друге, мета незрозуміла. Вам дійсно потрібен довший коментар, який містить контекст, чому є випадкові коментовані рядки. Коли я бачу лише коментований рядок коду, я повинен дослідити, як він потрапив туди, щоб зрозуміти, чому він потрапив туди. Хто це написав? Що робити? Яким було повідомлення / контекст комісії? Etcetera.

Розглянемо альтернативи:

• Якщо мета - навести приклади використання функції / api, то надайте одиничний тест. Тести одиниць - справжній код, і вони порушуються, коли вони більше не відповідають правильності.
• Якщо метою є збереження попередньої версії коду, використовуйте керування джерелом. Я набагато краще оформити попередню версію, а потім переключити коментарі на всій кодовій базі, щоб "повернути" зміни.
• Якщо мета полягає в тому, щоб підтримувати альтернативну версію того ж самого коду, використовуйте вихідний контроль (знову). Саме для цього потрібні гілки.
• Якщо метою є уточнення структури, подумайте, як можна переструктурувати код, щоб зробити його більш очевидним. Більшість інших відповідей є хорошими прикладами того, як ви могли це зробити.

Найбільша проблема цього коду полягає в тому, що ви дублювали ці 6 рядків. Щойно ви усунете це дублювання, цей коментар марний.

Якщо ви створюєте boutiqueDao.mergeOrPersistметод, ви можете переписати це як:

if (boutique == null) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

boutiqueDao.mergeOrPersist(boutique);

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

Багато ORM якимось чином підтримують це. Наприклад, вони можуть створити новий рядок, якщо idнуль, і оновити існуючий рядок, якщо idвін не дорівнює нулю. Точна форма залежить від конкретної ORM, і оскільки я не знайомий з технологією, яку ви використовуєте, я не можу вам у цьому допомогти.

Якщо ви не хочете створити mergeOrPersistметод, вам слід усунути дублювання іншим способом, наприклад, ввівши isNewBoutiqueпрапор. Це може бути не дуже, але все ж набагато краще, ніж дублювати всю логіку призначення.

bool isNewBoutique = boutique == null;
if (isNewBoutique) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

if (isNewBoutique)
    boutiqueDao.persist(boutique);
else
    boutiqueDao.merge(boutique);

Це абсолютно жахлива ідея. Зрозуміло, що це за наміри. Чи забудовник помилково прокоментував рядок? Щоб щось перевірити? Що відбувається?!

Окрім того, що я бачу 6 рядків, які в обох випадках абсолютно рівні. Швидше, ви повинні запобігти дублюванню цього коду. Тоді стане зрозуміліше, що в одному випадку ви додатково викликаєте setSelected.

Ні, це жахлива ідея. Виходячи з цього коду, на думку мені приходять такі думки:

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

Побачивши тисячі рядків коментованого коду, я зараз роблю єдине розумне, коли бачу: негайно видаляю його.

Немає розумних причин перевіряти коментований код у сховище.

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

Я просто хотів би додати відповідь CodesInChaos, вказавши, що ви можете переробити її далі в невеликі методи . Обмін загальною функціональністю за складом уникає умов:

function fill(boutique) {    
  boutique.setSite(site);
  boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
  boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
  boutique.setNom(fluxBoutique.getNom());
  boutique.setIdWebSC(fluxBoutique.getId());
  boutique.setDateModification(new Date());
}    

function create() {
  boutique = new Boutique();      
  fill(boutique);
  boutique.setSelected(false);
  return boutiqueDao.persist(boutique);
}

function update(boutique) {
  fill(boutiquie);
  return boutiquieDao.merge(boutique); 
}

function createOrUpdate(boutique) {
  if (boutique == null) {
    return create();
  }
  return update(boutique);  
}

Хоча це явно не є гарним випадком для коментованого коду, є ситуація, на яку я думаю, що це вимагає:

// The following code is obvious but does not work because of <x>
// <offending code>
<uglier answer that actually does work>

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

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

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

// Не потрібно знімати вибір цього бутіка, оскільки [ЩО БЕЗ]

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

%% Векторизований код нижче:

% for ii in 1:N
%    for jj in 1:N
%      etc.

%, але версія матриці працює на 15 разів швидше на типовому вході (MK, 03.10.2013)

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

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

## Enable support for mouse input:
# enable_mouse = true

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

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

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

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

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

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

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

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

Name:           foomatic
Version:        3.14
 ...
Source0:        %{name}-%{version}.tar.gz

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

Name:           barmatic
Version:        2.71
 ...
# This package has no sources.
# Source0:        %{name}-%{version}.tar.gz

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

if ( condition ) {
  foo();
  // Under most other circumstances, we would do a bar() here, but
  // we can't because the quux isn't activated yet.  We might call
  // bletch() later to rectify the situation.
  baz();
}

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

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

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

Це не виглядає добре приятелем.

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

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

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

Інакше тут можна спробувати щось гнучкіше, щось подібне

boutique.setSite (сайт) можна замінити на

setsiteof.boutique (сайт). Існують різні аспекти та перспективи OOP, завдяки яким можна збільшити читабельність.

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