Какво ви е мнението за коментирането на кода?
И моето мнение е, че коментарите рядко са ценни. Обаче по-долу има
няколко примера за случаи, в които са ми вършили работа.
>
> Ако искате да комуникирате странни обстоятелства, кръщавайте методи и
> променливи с имена, които провокират мислене: 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-тата и коментарите като
цяло, но когато са ми полезни (минали са две-три ментални цедки) си
пратикувам прагматичния фашизъм.
Н.
Най-малкото, част от платформата е т.нар. JavaDoc. Кометираш си
методите със специални тагове, като коментарът започва леко по-
различно от стандартните многоредови коментари (/**, вместо с една
звездичка /*). На базата на това се генерират едни HTML-и, които ти
описват API-то, а пък модерните IDE-та (Eclipse, NetBeans, InteliJ и
пр.) дават информация за въпросния метод. Наистина доста е ценно,
когато се налага да се ползват някакви чужди API-та без да имаме
достъп до метода...
Май малко постно го обясних, но предполагам повечето от вас са минали
през Java и знаят какво имам впредвид
Но тук най-вероятно не става дума за документиране на APIs.
Но първо да кажа своето мнение за вътрешно-кодови коментари. Лично аз
ги слагам в случай, че кодът ми се отклонява от разбираемото с цел да
постигна някаква оптимизация. След известно време и аз забравям защо
съм го направил така, да не говорим за някой друг, на който се налага
да ми пипне кода.
Точно в това отношение деля езиците на сериозни и несериозни (май
обаче наистина това определение е малко крайно). Ако върху едни и същи
файлове (класове, скриптове и пр.) могат да работят повече от трима
души, без да си пречат и да чупят нищо, езикът е сериозен. Динамичните
езици според мен са идеални двама души да направят набързо качествен
сайт, но не и за нещо повече. Просто тези неща не scale-ват. Може би
това е някаква градска легенда, каквато легенда е, че Java-та е по-
бавна от C++, не знам...
Естествено, това е религиозен спор, подходящ за друга тема (не му е
мястото в темата за коментарите). А и нямам и 1/10 от опита на всеки
един от вас в света на динамичните езици.
# This is ugly, but there is no way it could work better.
http://bugs.mysql.com/bug.php?id=6071
Другото, което отдавна не правя, е да комитвам коментиран код. Вие
правите ли го? Аз трия безпардонно.
Иначе кофти вкус оставиха тия моджехидински изказвания, наистина. Нека
да не принизяваме дискусиите до нивото "моя език ще набие твоя". Първо
не е забавно, второ за никому не е полезно. Както и да си разправяме
какво съм чул от комшийчето за еди какво си. Ако ще е така, по убуу
хич да не е. Говорихме за language agnostic, защото вярвам че можем да
научим много един от друг, точно щото ползваме различни инструменти.
Другото, което отдавна не правя, е да комитвам коментиран код. Вие
правите ли го? Аз трия безпардонно.
Иначе кофти вкус оставиха тия моджехидински изказвания, наистина. Нека
да не принизяваме дискусиите до нивото "моя език ще набие твоя". Първо
2009/12/8 Petyo Ivanov <unde...@gmail.com>
Другото, което отдавна не правя, е да комитвам коментиран код. Вие
правите ли го? Аз трия безпардонно.
Винаги! На който му трябва, да си го търси из историята в сорс контрола!
Донякъде е забавно, но нека направим нова тема за целта. Много добре тролирам на темата, че C++ и Java са гнусни езици, да знаете :-)