LINUX.ORG.RU
ФорумTalks

Философия идеального кода: нужны ли комментарии?


0

4

Вопрос кроется в заголовке.

Иллюстрация (и ответ): http://img17.imageshack.us/img17/2053/64762894.png

Очевидно, что смысла писать комментарии методов нет. Тем не менее, во многих «конторах» за отсутствие комментариев подобного рода по головке не погладят.

Классический пример библиотеки вообще без комментариев mybatis - и, что примечательно, пользоваться ей одно удовольствие!

Коментарии нужны, но они должны быть адекватными - только там, где без них тяжело понять, для чего это нужно/как это работает.

Shtsh ★★★★ ()

Рыба гниёт с головы.

Если написать нечего - никакой язык программирования не поможет.

pacify ★★★★★ ()
Ответ на: комментарий от CYB3R

Лучше уж комментарий на хорошем русском чем на плохом английском (который никто кроме автора, в том числе нативы, не поймет)

DNA_Seq ★★☆☆☆ ()

Прозреваю что в камментах псевдокод.

DNA_Seq ★★☆☆☆ ()

где тип возвращаемого значения?

wxw ★★★★★ ()
Ответ на: комментарий от Shtsh

они должны быть адекватными - только там, где без них тяжело понять, для чего это нужно/как это работает.

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

belous_k_a ()
Ответ на: комментарий от belous_k_a

Как минимум три раза повторяющаяся информация. Как максимум из названия метода в принципе понятно что он делает.

А, так ты в этом ключе. Ну да. ЕДинственное, я не согласен с тем, что русские комментарии не Ъ.

VirRaa ★★★ ()

В меру все хорошо. Прокомментировать сложные места - нужно. Комменты же в стиле

i += 1 // Увеличиваем счетчик на 1

не нужны.

Ну и не надо путать комментарии с тегами автодокументации.

provaton ★★★★★ ()

чего не так-то? из этого потом отдельная документация генерится.
man doxygen, javadoc итп.
реализация скрыта, исходники недоступны. всё, что тебе видно - это апи, и те строчки документации, на которые ты так недоумеваешь.

aol ★★★★★ ()

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

blexey ★★★★★ ()
Ответ на: комментарий от blexey

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

belous_k_a ()

Это не комментарии, а докстринги.

baverman ★★★ ()

Это иллюстрация поговорки о дураке и стеклянном фаллосе.

«Пиши программу так, как будто объясняешь другому человеку, чего ты хочешь от компьютера.» (вроде бы Кнут, очень вольный перевод).

stormy ()
Ответ на: комментарий от stormy

Но вообще да, больше похоже не на комментарии, а на болванку для какого-нибудь доксиджена.

stormy ()

Комментарии должны объяснять не _что_ делается (это и по коду понятно), а _зачем_ делается _именно так_.

lodin ★★★★ ()

В идеальном коде комментариев быть не должно ибо self-explained. Т.к. идеальных программистов нет (мало), комментариев должно быть столько и ровно столько, чтобы дополнять код до самодокументирующегося состояния.

schizoid ★★★ ()

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

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

Mironor ()
Ответ на: комментарий от belous_k_a

для тех кто не в теме - это не повторяющийся камент, и не для других программеров, это всего лишь для системы автодокументации

q11q11 ★★★★★ ()
Ответ на: комментарий от q11q11

Для тех кто не в теме, систему автодокументации мы сами писали 8).

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

Т.е. по сути это вредный шум.

belous_k_a ()

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

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

Комментарии от капитана очевидности вроде «метод String IntToString(int value) преобразовывает число value в строку» только замусоривают код, IMHO.

BattleCoder ★★★★★ ()

Зависит от языка и специфики проекта. Например, если проект на ASM - без комментариев не обойтись.

Или как-то так:

Коментарии нужны, но они должны быть адекватными - только там, где без них тяжело понять, для чего это нужно/как это работает.

observer ★★★ ()
Ответ на: комментарий от BattleCoder

BattleCoder

Комментарии не нужны.

а если используется алгоритм сложнее «пузырьковой сортировки»? А если какое-то логически очень простое условие записано нетривиально? типа «сеня выпил пива» в комменте, а в программе «это сеня && (у сени >= 40руб || сеню угостили друганы)»

drBatty ★★ ()
Ответ на: комментарий от belous_k_a

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

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

Не изведутся посты про нужность комментирования, покуда подрастает молодняк программистов =)

Siado ★★★★★ ()
Ответ на: комментарий от RedNikifor

Почему никто не сказал ТС-у про шрефты?

Потому что это Java-IDE, а там шрифты настолько неисправимы, что про них даже упоминать не хочется.

Siado ★★★★★ ()
Ответ на: комментарий от lodin

Комментарии должны объяснять не _что_ делается (это и по коду понятно), а _зачем_ делается _именно так_.

Вот это дельный подход к комментированию.

Siado ★★★★★ ()
Ответ на: комментарий от Siado

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

Милейший, жиденько вы как... то, этому проекту уже 4 года (с перерывом на 2011 год). Если я смотрю сигнатуру метода то легко могу сказать что там деется, если процитированный комментарий без сигнатуры - то нет. Все просто - сигнатура несет информацию, а комментарий - шумит.

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

belous_k_a ()

если обязывают писать именно такие комментарии - менеджемент неадекватен и в конторе лучше не работать; психическое здоровье позволит сохранить профессионализм на нужном уровне

ak369260 ()
Ответ на: комментарий от CYB3R

Ява и C# полностью поддерживают юникод, можно писать комментарии хоть на китайском, оформляя юникодной же псевдографикой.

note173 ★★★★★ ()
Ответ на: комментарий от belous_k_a

+100500

все правильно сказано

сущности не следует преумножать без необходимости

ak369260 ()
Ответ на: комментарий от ufw

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

belous_k_a ()
Ответ на: комментарий от BattleCoder

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

Задолбаешься читать строки по килобайту длиной, в конце чтения забудешь с чего начинал. ~10К слов недостаточно для однозначного короткого обзывания всех переменных и функций, будут повторы.

Комментарии не нужны.

А вдруг забудешь фичу или константу? В релизе лишние комменты не нужны, так будет точнее.

Napilnik ★★★★★ ()

комментарии нужны для прояснения контекста (предметной области) реализации - если оный из имен структур данных не очевиден.

зы. и да, сабж докстринги

VladimirMalyk ★★★★★ ()

[Кэпов тред]. О чём он кстати? О нелепостях, порождаемых системами автодокументации? И почему методы не нуждаются в комментариях, интересно?

Virtuos86 ★★★★★ ()
Ответ на: комментарий от CYB3R

Поддерживаю. Приходилось работать с кодом комментированым на итальянском + некоторые переменные на ихнем же. Пока не въехал в проект это было что-то...

urxvt ★★★★★ ()
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.