Comments in Loop

Качество продукта начинается с красивых метрик кода. О том, что комментарии к коду только повышают его эффективность, уже говорилось в нескольких моих статьях ("Easy white-box testing", "Качество кода одним числом", "Документор кода или псевдокод"). Хотелось бы их подкрепить результатами исследований. Надеюсь, чарты сильнее убедят ваших программистов вставлять пояснения в код.

Для исследования были взяты две процедуры (с комментариями в цикле cmt_in loop и идентичная без комментариев cmt_no_loop) на PL/SQL Oracle:
  PROCEDURE cmts_in_loop
  IS
    t1 timestamp;
    t2 timestamp;
    l  varchar2(50);
  BEGIN
    t1 := SYSTIMESTAMP;
    FOR i IN 1..1000000 LOOP
      -- 1-st comment line in loop
      l := 'one command line in loop with comments';
      -- 2-nd comment line in loop
    END LOOP;
    t2 := SYSTIMESTAMP;
    dbms_output.put_line('timestamp for mln-loop with 2 comments: ' || to_char(t2 - t1, 'MI:SS.FF5'));
  END;
/
  PROCEDURE cmts_no_in_loop
  IS
    t2 timestamp;
    t3 timestamp;
    l  varchar2(50);
  BEGIN
    t2 := SYSTIMESTAMP;
    FOR i IN 1..1000000 LOOP
      l := 'one command line in loop without comments';
    END LOOP;
    t3 := SYSTIMESTAMP;
    dbms_output.put_line('timestamp for mln-loop without comments: ' || to_char(t3 - t2, 'MI:SS.FF5'));
  END;
/

Визуализируем и вычислим метрики кода в специализированном продукте ClearSQL:

Flowchart - cmts_in_loop

Flowchart - cmts_no_loop

По диаграммам Flowchart видно, что в обеих процедурах одинаковое количество узлов и рёбер, то есть наличие или отсутствие комментариев не влияет на цикломатическую сложность.

Измерение метрик кода дали следующие цифры:
 
Различные цифры в разрезе процедур подсвечены мной красным цветом. За счёт наличия строк-комментариев в первой процедуре вырос Maintainability Index - важная величина кода, которая чем выше, тем лучше код (подробные исследования функции смотрите в "Качество кода одним числом").
Да, идентичная программа с комментариями стоит дороже при изготовлении и поддержке, так как вместе с правкой значимых строк необходимо актуализировать и их примечания. Но это только по меркам компании Conquest Software Solutions, которая "с потолка" взяла формулу и коэффициенты для исчисления Technical Dept.

Описание Technical Dept

А теперь ударный аргумент - время на исполнение цикла.

Дельта выполнений первой и второй процедур 26 раз

Собрав результаты от пары дюжин выполнений, на график была выведена разница времени исполнения цикла с комментариями (cmt_in_loop) и времени выполнения аналогичного цикла, но без строк комментариев (cmt_no_loop). Да, по этому небольшому расхождению слегка заметно, что комментарии затягивают цикл. Но эта гипотеза была разрушена уже на второй сотне экспериментов:

Дельта выполнений первой и второй процедур 201 раз

То есть циклы без комментированных строк крутились дольше! Казалось бы - нонсенс, что увеличение строк в цикле убыстряет его ход, но видимо даже компилятору полезнее иметь код с пояснениями, а не только новичку программисту, правящему легаси.

Так что, решающим аргументом для добавления разъяснений в код стоит рассматривать следующее:
- комментарии не загружают текст, а наоборот помогают читать его;
- блок-схемы процедур "с" и "без" комментариев идентичны;
- комментарии никак не влияют на цикломатическую сложность;
- за счёт строк комментариев легко и быстро увеличить MI, то есть улучшить качество;
- комментарии даже в цикле не замедляют исполнение, а ускоряют его.

О том, сколько строк рабочих и вспомогательных оптимально (3/1) должно быть в коде, читайте в статье "Качество кода одним числом". Метрики кода могут показать общее количество и пропорцию строк, а настраиваемые правила для автоматической проверки выявят места с недоработками. В ClearSQL это называется Code Review Rule Editor, с помощью которого можно добавить пользовательские правила и проверять их в том же автоматическом режиме наряду со встроенными (~200штук).
О том, как проще добавлять пояснения в код, читайте в "Документор кода или псевдокод".