Коментари

7 views
Skip to first unread message

Stefan Kanev

unread,
Dec 7, 2009, 6:34:22 PM12/7/09
to software-crafst...@googlegroups.com
Какво ви е мнението за коментирането на кода?

Знам, че Петьо е абсолютния фашист в това отношения. Веднъж видя един ред който аз бях написал и посегна към мотиката. Макар да имах по-умерено мнение, започвам да вървя към неговия екстремистки лагер. Намирам повечето коментари за code smell. Малката част от останалите намирам за губещи смисъл твърде бързо за да има смисъл от тях на първо място. На както казах, (1) това е екстремната ми позиция и то (2) пишейки на Ruby, където ако не можеш да се изразиш кратко и ясно, имаш нужда от въвеждащ курс в програмирането.

Какво е вашето становище по въпроса? Как го правите във вашата фирма?

Hristo Deshev

unread,
Dec 8, 2009, 3:41:15 AM12/8/09
to software-crafst...@googlegroups.com
Здрасти,

Страхотен пост - тъкмо скоро имах приключения по темата. Отговарям по-долу.

2009/12/8 Stefan Kanev <stefan...@gmail.com>

Какво ви е мнението за коментирането на кода?

И аз съм от фашистите. Миналата седмица с голямо неудоволствие сложих коментар на едно място, за да напомня, че грозната имплементация е такава, за да заобиколи бъг в NHibernate. Вчера местих методи и забелязах, че коментарът е останал да виси във въздуха. Изтрих го. За пореден път се убеждавам, че файда от коментарите няма.

Ако искате да комуникирате странни обстоятелства, кръщавайте методи и променливи с имена, които провокират мислене: WorkAroundNHibernateLinqBug() и т.н.

Иначе си позволявам понякога да слагам коментари в стил //TODO: don't forget XXX, но това са ми винаги краткосрочни напомняния за конкретната работна сесия. Преди commit винаги ги чистя. Отдавна имам навик да преглеждам диффовете преди commit и не си позволявам да вкарвам в гит репото такива боклуци.

Поздрави,
Христо

Nikolay Bachiyski

unread,
Dec 8, 2009, 4:33:24 AM12/8/09
to software-crafst...@googlegroups.com
2009/12/8 Hristo Deshev <hri...@deshev.com>:

> 2009/12/8 Stefan Kanev <stefan...@gmail.com>
>>
>> Какво ви е мнението за коментирането на кода?
>

И моето мнение е, че коментарите рядко са ценни. Обаче по-долу има
няколко примера за случаи, в които са ми вършили работа.

>
> Ако искате да комуникирате странни обстоятелства, кръщавайте методи и
> променливи с имена, които провокират мислене: WorkAroundNHibernateLinqBug()
> и т.н.

// each condition has to contain a %s not to break the sequence
$where[] = is_null( $entry->context )? '(context IS NULL OR %s IS
NULL)' : 'BINARY context = %s';

Става дума за заобикалка, но само заради този ред не ми се прави нова
функция, че да включа заобикалката в името ѝ.

Другият случай, в който са ми полезни е много ниското ниво:

// The magic is 0x950412de
// bug in PHP 5.0.2, see
https://savannah.nongnu.org/bugs/?func=detailitem&item_id=10565
$magic_little = (int) - 1794895138;
$magic_little_64 = (int) 2500072158;

И още едно:

// headers' msgid is an empty string
fwrite($fh, pack('VV', 0, $current_addr));

В някой от тези случаи съм минавал през код, в който вадя парчета в
смислени функции, но обикновено не си заслужава.

>
> Иначе си позволявам понякога да слагам коментари в стил //TODO: don't forget
> XXX, но това са ми винаги краткосрочни напомняния за конкретната работна
> сесия. Преди commit винаги ги чистя. Отдавна имам навик да преглеждам
> диффовете преди commit и не си позволявам да вкарвам в гит репото такива
> боклуци.

Аз пък по-често оставям TODO-та в кода, току-виж някой ги оправил :-)

Забелязал съм, че ако в системата има относително тривиален бъг с
нисък приоритет, той рядко бива поправян сам по себе си. Обикновено
някой го оправя, когато прави нещо по-важно с кода около него.

Ето пример от инсталационната част на уеб приложение:

// TODO: check if the .htaccess is in place or try to write it before
showing instructions
$show_htaccess_instructions = $show_htaccess_instructions && empty( $errors );

Знам, че това сега не ми е проблем и не вярвам да седна да го оправям
ей така, защото си нямам работа. Другата седмица (или в някакъв
момент, или някой друг), обаче, ще се занимавам с инсталатора
по-сериозно. Имам два варианта:

0. Слагам това като бъг в системата. Евентуално му слагам етикет като
install и се надявам, че като пипам по инсталатора по-сериозно ще видя
всичко друго с етикет install. Фактът, че имаме удобен етикет като
install е късмет. Категоризацията на бъговете на дребно не винаги е
толкова лесна задача.

1. Оставям това TODO, което внася шум в кода, но оставя проблемът в
най-близкия му контекст.

Рядко избирам 1., но не го отхвърлям по принцип.

На кратко: опитвам се да ограничавам TODO-тата и коментарите като
цяло, но когато са ми полезни (минали са две-три ментални цедки) си
пратикувам прагматичния фашизъм.

Н.

ivko3

unread,
Dec 8, 2009, 7:46:26 AM12/8/09
to Software craftsmanship Bulgaria
В сериозните езици като Java, където пишем малко повече от PHP, Ruby,
Python, и пр., също не може без коментари. Колкото и да си добър
програмист, да спазваш всички pattern-и и кодът ти да говори сам за
себе си, коментарите си трябват.

Най-малкото, част от платформата е т.нар. JavaDoc. Кометираш си
методите със специални тагове, като коментарът започва леко по-
различно от стандартните многоредови коментари (/**, вместо с една
звездичка /*). На базата на това се генерират едни HTML-и, които ти
описват API-то, а пък модерните IDE-та (Eclipse, NetBeans, InteliJ и
пр.) дават информация за въпросния метод. Наистина доста е ценно,
когато се налага да се ползват някакви чужди API-та без да имаме
достъп до метода...

Май малко постно го обясних, но предполагам повечето от вас са минали
през Java и знаят какво имам впредвид

Mitko Kostov

unread,
Dec 8, 2009, 7:54:01 AM12/8/09
to software-crafst...@googlegroups.com
Само за протокола, в несериозните езици като Ruby, Python и PHP също има
подобни решения: http://yardoc.org/,
http://docs.python.org/library/pydoc и http://www.phpdoc.org/.

Но тук най-вероятно не става дума за документиране на APIs.

Stefan Kanev

unread,
Dec 8, 2009, 7:54:04 AM12/8/09
to software-crafst...@googlegroups.com
Мисля, че е разумно да правим разлика между коментари и документация. JavaDoc-а си документация. Обикновено прилагаш върху публични интерфейси и вътрешна структура.

С това настрана, като бивш "сериозен" Java програмист съм несъгласен с теб. 90% от инфраструктурата ти може да се прокомуникира с измежду добро познание на ОО принципи и канонично използване на няколкото слоя архитектура (Hibernate + Spring, например). А ако си говорим в рамките на един метод (където имаш коментар, а не документация) ми е интересно да видя пример. Много от нещата които Ники изброи си струват коментарите, но в едно съвременно Java приложение те би трябвало да са code smells. Или бъркам.

Отделно, странно ми че казваш "в сериозните езици като Java" и поставяш "PHP, Ruby и Python" като контраст. Интересно ми е какво те кара да мислиш, че някой от другите три е несериозен или има по-различни изисквания към коментари/документация. 

2009/12/8 ivko3 <ivan.st...@gmail.com>

ivko3

unread,
Dec 8, 2009, 9:06:26 AM12/8/09
to Software craftsmanship Bulgaria
Знаех си, че ще има такава реакция на епитета "сериозен език" ;-)

Но първо да кажа своето мнение за вътрешно-кодови коментари. Лично аз
ги слагам в случай, че кодът ми се отклонява от разбираемото с цел да
постигна някаква оптимизация. След известно време и аз забравям защо
съм го направил така, да не говорим за някой друг, на който се налага
да ми пипне кода.

Точно в това отношение деля езиците на сериозни и несериозни (май
обаче наистина това определение е малко крайно). Ако върху едни и същи
файлове (класове, скриптове и пр.) могат да работят повече от трима
души, без да си пречат и да чупят нищо, езикът е сериозен. Динамичните
езици според мен са идеални двама души да направят набързо качествен
сайт, но не и за нещо повече. Просто тези неща не scale-ват. Може би
това е някаква градска легенда, каквато легенда е, че Java-та е по-
бавна от C++, не знам...

Естествено, това е религиозен спор, подходящ за друга тема (не му е
мястото в темата за коментарите). А и нямам и 1/10 от опита на всеки
един от вас в света на динамичните езици.

Krasimir Angelov

unread,
Dec 8, 2009, 9:13:05 AM12/8/09
to software-crafst...@googlegroups.com
On Tue, 2009-12-08 at 06:06 -0800, ivko3 wrote:
> Ако върху едни и същи
> файлове (класове, скриптове и пр.) могат да работят повече от трима
> души, без да си пречат и да чупят нищо, езикът е сериозен. Динамичните
> езици според мен са идеални двама души да направят набързо качествен
> сайт, но не и за нещо повече. Просто тези неща не scale-ват.

Nigga, please!

Petyo Ivanov

unread,
Dec 8, 2009, 9:50:48 AM12/8/09
to Software craftsmanship Bulgaria
Последния коментар, който ясно си спомням да съм написал:

# This is ugly, but there is no way it could work better.
http://bugs.mysql.com/bug.php?id=6071

Другото, което отдавна не правя, е да комитвам коментиран код. Вие
правите ли го? Аз трия безпардонно.


Иначе кофти вкус оставиха тия моджехидински изказвания, наистина. Нека
да не принизяваме дискусиите до нивото "моя език ще набие твоя". Първо
не е забавно, второ за никому не е полезно. Както и да си разправяме
какво съм чул от комшийчето за еди какво си. Ако ще е така, по убуу
хич да не е. Говорихме за language agnostic, защото вярвам че можем да
научим много един от друг, точно щото ползваме различни инструменти.

Hristo Deshev

unread,
Dec 8, 2009, 11:34:27 AM12/8/09
to software-crafst...@googlegroups.com
2009/12/8 Petyo Ivanov <unde...@gmail.com>


Другото, което отдавна не правя, е да комитвам коментиран код. Вие
правите ли го? Аз трия безпардонно.

Винаги! На който му трябва, да си го търси из историята в сорс контрола!

 

Иначе кофти вкус оставиха тия моджехидински изказвания, наистина. Нека
да не принизяваме дискусиите до нивото "моя език ще набие твоя". Първо


Донякъде е забавно, но нека направим нова тема за целта. Много добре тролирам на темата, че C++ и Java са гнусни езици, да знаете :-)

Поздрави,
Христо

Stefan Kanev

unread,
Dec 8, 2009, 12:34:56 PM12/8/09
to software-crafst...@googlegroups.com
2009/12/8 Hristo Deshev <hri...@deshev.com>
2009/12/8 Petyo Ivanov <unde...@gmail.com>


Другото, което отдавна не правя, е да комитвам коментиран код. Вие
правите ли го? Аз трия безпардонно.

Винаги! На който му трябва, да си го търси из историята в сорс контрола!

+1 отново. Оставам шокиран като някой къмитне закоментиран код.

 Донякъде е забавно, но нека направим нова тема за целта. Много добре тролирам на темата, че C++ и Java са гнусни езици, да знаете :-)

Уоу, имаш предвид C++ и C#, нали? :) 
Reply all
Reply to author
Forward
0 new messages