11.06.2009

Комментарии

/**
 * По-хорошему, объем комментариев должен быть не меньше
 * объема самого кода или даже больше. Я вообще стараюсь
 * сначала комментарий написать, а потом уже кусок кода.
 * Если русским языком не можешь сформулировать, что хочешь
 * чтобы код делал, значит рано еще сам код писать. Скажу
 * больше, акт написания комментария заставляет мозг
 * напрячься и обрести ясность мысли, что способствует
 * написанию стройного и четкого кода. Вы не замечали
 * за собой такого?
 */

17 комментариев:

Анонимный комментирует...

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

причина: после некоторого времени жизни кода, код и комментарий перестают соответствовать друг другу, т.к. в код вносятся правки, а в комментарий -- нет. в результате комментарии перестают помогать и начинают путать.

комментарии должны нести смысл, но не должны дублировать сказанное кодом.

--
misha@

kulikov.dm комментирует...

код обильно «политый» комментариями — это плохой запах (М. Фаулер). Если код требует такого количества комментариев — это повод задуматься.

по комментариям очень легко искать места, требующие рефакторинга.

при этом я всегда пишу комментарии там, где это необходимо, таким образом оставляя для себя заметки в местах, над которыми еще стоит подумать. возвращаюсь к таким местам спустя какое-то время и «рефакторю» их так, чтобы пропала необходимость в комментировании.

Степан Резников комментирует...

А я и не говорю, что комментрии должны дублировать сказанное кодом. Разумеется, комментарии к тривиальным конструкциям не нужны и даже вредны.

Степан Резников комментирует...

>> «рефакторю» их так, чтобы пропала необходимость в комментировании.

Я бы тоже так хотел уметь - писать код, который сам за себя все разъясняет, что и комментарии не нужны. А пока я так не умею, поэтому пишу комментарии :)

Анонимный комментирует...

А я начинаю с блок схемы. Тогда сразу ясно какие комменты и куда нужны.

DenisX комментирует...

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

Вадим Макишвили комментирует...

Полностью разделяю.

Для меня естественно, что речь идет не о дублировании сказанного кодом и естественно, что при рефакторинге кода нужно обязательно рефакторить комментарии. Речь-то не об этом вовсе.

Речь о самодокументировании кода, об удобной работе в команде, о быстром въезжании в мой код коллег и последователей.

Отсутствию комментариев в командном коде есть только одно реальное объяснение — лень . Аргументация, что мол нет времени — это безуспешная попытка прикрыть лень :)

Категорично получилось :)

Chikey комментирует...

Вот честно - комментарии - зло.

Или может я один не видел достойных коментов.

Вот взять тот же jQuery от того же рейсига.


// The current version of jQuery being used
jquery: "1.3.2",

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

Степан Резников комментирует...

Пример хороших комментариев в коде:
http://code.google.com/p/jtweener/source/browse/trunk/src/jTweener.js

Такими библиотеками пользоваться одно удовольствие! :)

Анонимный комментирует...

про http://code.google.com/p/jtweener/source/browse/trunk/src/jTweener.js

плохие там комментарии, ну сам посмотри:

/** @type {Boolean} Говорит, что текущий браузер — Internet Explorer */
var is_msie = /msie/.test(userAgent) && !/opera/.test(userAgent);

is_msie ничего более означать и не должен. никогда. имя переменной говорит само за себя. комментарий ненужен.


/** Действия для нэймспэйсов */
var nsActions = {};

те, кто уделят 3 минуты изучению кода поймут, что ns == name sample. а переводить action смысла нет.


/**
* Стандартные значения анимации, который будут подставляться в каждый
* <code>addTween()</code>, если они не указаны
*/
var defaultOptions = {...


вот ни за что бы не догадался, что в переменной с именем defaultOptions лежат "стандартные значения"


дальше даже смотреть не стал :)

--
misha@

Анонимный комментирует...

да, забыл написать: если речь идёт не о дублировании текстом функционала, то я не представляю, что-же надо описывать в комментариях, чтобы их размер был больше размера кода %-)

--
misha@

Сергей Чикуёнок комментирует...

вот ни за что бы не догадался, что в переменной с именем defaultOptions лежат "стандартные значения"

А догадался бы, что они «будут подставляться в каждый addTween(), если они не указаны»? :)

А вообще комментарии я пишу в первую очередь для нормальных IDE вроде IDEA или Eclipse, которые вместе с code complete показывают эту самую документацию

дальше даже смотреть не стал :)

И очень зря :) Хотелось бы узнать мнение, например, о комментарии к переменной re_value или методу getRGB.

Dzyanis Kuzmenka комментирует...

Абсолютно с вами согласен Степан. Мой опыт совсем не большой, но ещё в колледже было замечено, сначала полностью представь как это будет работать и тогда все получится не через жопу. Места которые не смог сам себе объяснить, будут заменятся говнокодом.

Ваш метод напоминает псевдокод Стива Макконнелла. Тот предлагает вначале все написать в виде псевдокода, а патом только наносить на него настоящий код, при этом псевдокод идёт уже как комментарий.

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

ast комментирует...

Раньше тоже очень любил комментарии.
Сейчас пришел к тому, что название любого метода, класса, переменной должно максимально полно отражать свое значение.

Комментарии нужны только для какой-нибудь особенно сложной бизнес логики или других неявных вещей.

Степан Резников комментирует...

Также как и Sergey, в яваскрипте стараюсь все комментарии писать в формате JsDoc.

Алекс комментирует...

Замечал... к слову, не так давно начал все комментировать (раньше опасался, что будет терятся стройность кода), но теперь однозначно уяснил, что комментарии выстраивают в голове четкий образ, потому что мы мыслим ведь на родном языке, а не функциями. Поэтому комментируем все!

Степан Резников комментирует...

@Алекс: Ну комментировать все не надо :) Вот пара цитат о комментариях великих программистов (из книги Coders at Work):

Jamie Zawinski:
You’ve got to say in the comment something that’s not there already. What’s it for? Either a higher-level or a lower-level description, depending on what’s most important. Sometimes the most important thing is, what is this for? Why would I use it? And sometimes the most important thing is, what’s the range of inputs that this expects?

Brendan Eich:
In some ways the code should speak for itself at the small level. It’s at the bigger level, the big monster function or the module boundary, that you need docs. So doc comments or things like them—doc strings. Embedding the test in the comment.