Do comments!

Коментарi, документацiя,
а також все що з цим пов’язане
i зможе зробити наш код ще кращим
Назар Герасимчук
December 7, 2018
Назар Герасимчук Коментарi etc. December 7, 2018 1 / 35

Що i до чого?
Не коментуйте поганий код –
перепишiть його.
Б. Кернiган i П. Плауер
Найкраща допомога розробнику – хороший коментар в кодi.
Найбiльше засмiчують код беззмiстовнi коментарi.

Не коментуйте поганий код –
перепишiть його.
Б. Кернiган i П. Плауер
Найкраща допомога розробнику – хороший коментар в кодi.
Найбiльше засмiчують код беззмiстовнi коментарi.
Найбiльшу шкоду приносить коментар який втратив свою
актуальнiсть (хибний, дезiнформативний).

Фiлософський погляд на коментарi
Насправдi коментарi –
неуникне зло.
Мови програмування недостатньо виразнi.
Програмування – процес невдалого виразу власних думок.

Насправдi коментарi –
неуникне зло.
Мови програмування недостатньо виразнi.
Програмування – процес невдалого виразу власних думок.
Коментарi – ознака невдачi. Гордитися тут нiчим.

Приклад до обговорення
Приклад до обговорення
Що сталося з коментарем i з тiєю стрiчкою яку вiн повинен був описувати?

Коментарi не компенсують поганого коду
Коментарi не компенсують поганого коду
Ви пишете модуль, i розумiєте що вiн
неконтрольовано розрiсся, став дуже заплутаним.
Тут, згадуєте цю презентацiюa
i думаєте «A давай-но
я зараз понаписую коментарiв, щоб код був
зрозумiлiший».
Нi! Так не буде краще. Потрiбно переписати код
модуля!
a
ну як вам рекурсiя?

Пояснюйте що ви робите в кодi
Пояснюйте що ви робите в кодi

Кориснi коментарi Юридичнi нотацiї
Юридичнi нотацiї

Кориснi коментарi Iнформативнi коментарi
Iнформативнi коментарi
1
2
1
Хiба не краще перейменувати метод?
2
Хiба не краще винести в спецiальний клас, що перетворює формати дати i часу?

Кориснi коментарi Пояснення намiрiв
Пояснення намiрiв
3
3
Автор вирiшив, що при порiвняннi двох об’єктiв об’єкти його класу повиннi
знаходитися в порядку сортування вище, чим об’єкти будь-якого iншого класу.

Кориснi коментарi Пояснення намiрiв
Пояснення намiрiв
4
4
Можна не погодитися з тим як автор вирiшує проблему, проте в крайньому разi ви
знаєте що саме автор намагається зробити.

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

Кориснi коментарi Пояснення i ризики
Пояснення i ризики
Виникає ризик що
коментар буде
неправильним. Це справдi
важко перевiрити, самi
переконайтеся.

Кориснi коментарi Попередження про можливi наслiдки
Попередження про можливi наслiдки
Можливо не найкраще
рiшення, але тут все
зрозумiло з цим тестом.

Хрестоматiйний приклад.

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

Кориснi коментарi Коментарi TODO
Коментарi TODO
Чого ф-iя не
реалiзована?
Реалiзувати потрiбно,
проте чомусь не
зараз.
Залежнiсть?
Функцiї в IDE.

Кориснi коментарi Коментарi TODO
Коментарi TODO
5
5
Тяжко жити, шкода вмерти. Не всi TODO-коментарi кориснi.

Поганi коментарi
Поганi коментарi
6
6
Що означає коментар? Хто цим буде займатися? Чого добивався автор? Чи може це
такий TODO-коментар?

Поганi коментарi Надлишковi коментарi
Надлишковi коментарi
7
7
Коментар читається не простiше нiж сам код. Коментар є неточним i нав’язує читачу
певнi iдеї якi можуть бути вiдмiннi вiд того що декларується в кодi.

Поганi коментарi Надлишковi коментарi
Надлишковi коментарi

Поганi коментарi Недостовiрнi коментарi
Недостовiрнi коментарi
Код зi слайду 25.
Метод не повертає керування
коли this.closed стає iстинним.

Метод повертає керування якщо
this.closed iстинне, iнакше,
чекає таймауту i генерує
виключення у випадку якщо
this.closed так i не стало
iстинне.

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

Поганi коментарi Журнальнi коментарi
Журнальнi коментарi
8
8
З моменту коли почали використовувати системи контролю версiй коду – про подiбнi
речi треба одразу ж забувати.

Поганi коментарi Шум
Шум

Поганi коментарi Небезпечний шум
Небезпечний шум
Яка користь з коментарiв такого
типу?
Це шумовi коментарi, викликанi
бажанням когось покоментувати.

типу?
Перечитайте уважнiше.

типу?
Знайшли помилку?

типу?
Знайшли помилку?
Ctrl+C + Ctrl+V
Якщо автори не слiдкують за
коментарями в момент написання,
то як можна очiкувати що такi
коментарi принесуть користь
читачам?

Поганi коментарi Коментар чи функцiя?
Коментар чи функцiя?
9
9
Iмовiрно програмiст спершу написав коментар, потiм по коментару написав
вiдповiдний код. Але вiн забув переглянути написаний код...

Поганi коментарi Закоментований код
Закоментований код
В програмуваннi навряд чи трапиться
звичка бiльш огидна як залишений
закоментований код.
Iншим програмiстам не вистачить хоробростi його видалити.
Чи важливi закоментованi стрiчки?
Може це просто мотлох?
Забули про систему контролю версiй?

Поганi коментарi Нелокальна iнформацiя
Нелокальна iнформацiя
10
10
Хто прослiдкує за змiною порта по замовчуванню?

Поганi коментарi Неочевиднi коментарi
Неочевиднi коментарi
11
11
Що таке байти фiльтра? Як вони пов’язанi з +1? Або з *3? Один пiксель вiдповiдає
одному байту? Чого 200?..

Цiкавi коментарi в iсторiї

Практична частина

Джерела I
Robert C. Martin.
Clean Code - a Handbook of Agile Software Craftsmanship.
Prentice Hall, 2009.
B. W. Kernighan and P. J. Plauge
The Elements of Programming Style.
New York, 1978.
Dennis Ritchie.
Odd Comments and Strange Doings in Unix.
http://web.archive.org/web/20040206202840/http://cm.bell-
labs.com/cm/cs/who/dmr/odd.html

Джерела II
Говнокод.ру
«По колено в коде» https://www.govnokod.ru/

Do comments!

Recommended

Recommended

More Related Content

Featured

Featured (20)

Do comments!