Разное

В последнее время пришлось разбирать много чужого кода. Кто этим занимался - меня поймет. Комментариев, естественно, ни строчки. Но вообще странно было бы требовать от других того, чего сам не делаешь.
Вспомнилось мне что хеопс упоминал о том, что хорошо откомментированный код экономит до 30% времени при его сопровождении. Звучит вкусно, но остается вопрос: а сколько времени занимает нормальное комментирование? быть может те же 30%, но при разработке? Что показывает практика?

много однозначно :)

ой да ладно.. если юзать IDE, то комментирование вообще на полуавтомате делается )
написать пару предложений "чо делает этот метад" не так уж и долго
зато комменты потом понадобятся каждому, кто читает код, включая тебя самого
если камментов нет 30 минут умножаешь на кол-во людей и получается уже большая трата времени :)

видимо не написал еще такого кода который мне бы самомму пришлось разбирать с коментариями...

Это не хорошо откомментированный, это просто код с комментариями. В хорошо откомментированном должно быть написано что метод делает, что принимает на входе, каких типов и что отдает на выходе. Желательные еще комментарии внутри самого метода... короче, чтобы потом сэкономить много времени, пары предложений, скорее всего, будет недостаточно.

Мне кажется надо писать самодокументирующийся код. Т.е. давать осмысленные имена функциям, классам, методам и т.д.
Например:

<? $tree = new treeClass; $tree->addNode(); $tree->moveNode(); $tree->removeNode(); $tree->showNode(); ?>

без комментирования ясно что и к чему.

Другое дело, что API общих классов всё равно надо документировать (чтобы пользователи класса элементарно знали какие методы в нём есть). Но тут сильно помогает PHPdoc.

И самодокументирующийся код и комментарии. И то и другое полезно. Сам по себе только самодокументирующийся код эффективен не будет.
У меня комментарии занимают минимум времени. Я об этом уже как-то рассказывал на тренинге в своем ЖЖ. Как быстро и эффективно комментировать код. Ничего там заумного нет. Просто привыкнуть надо.

пишу комментарии только в AS (Flash), потому что там пока плаваю и собственные
комментарии сильно помогают при переделке или повторном употреблении кода.
в РНР комменты пишу иногда, сильно бесит реклама сайтов в бесплатных скриптах,
ее удаляю сразу, комменты, написанные кем-то другим, обычно мало помогают (мне),
уж лучше поломать голову, но понять, как код работает. а комменты потом можно и
свои добавить, понятные :)

Так я в большинстве случаев для себя и пишу. Но если коммент выполнен грамотно, так что можно из него прочитать, что у нас на входе и на выходе, а также назначение функции или библиотеки, то тут пойдет и чужой коммент. После чего ломать голову можно будет минимально.

> TXC (28.05.2008 в 17:33)

Вам следует вести лекции в ведущих технических ВУЗ'ах страны.

Тонкий английский юмор?

Нет, скорее арабский.

Если комментирование воспринимается как отдельная от кодирования работа, то времени уходит много, оно ощутимо и раздражает. Очень много зависит от того, сколько времени проект живет и сколько народу над ним трудится, если больше полугода и больше двух человек, то комментирование зачастую экономит массу времени на коммуникации между разработчиками. Я конечено немного необъективен, так как просто физически вынужден комментировать код (разработчиков несколько - система одна, кроме того, любой участок кода может быть использован в любой момент либо в публичном приложении, либо в книге и комментировать вторично желание не возникает - поэтому любой даже захудалый код приходится оформлять и комментировать).