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

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

А что в иллюстрации не так?

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

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

Комментарий не на английском - оторвать руки.

А вдруг это кусок Национальной Программной Платформы, мало ли.

Комментарий не на английском - оторвать руки.

В 1С коменты тоже на английском писать?

Программа на 1С - оторвать руки.

На шарпе? Не смеши!

Программа на 1С - оторвать руки.

Ты такой же неадекват, как граф Дракула. Тот тоже всех мечтал на кол посадить.

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

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

Это жаба, хотя и в шарпе код будет валидным.

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

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

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

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

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

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

Комментарий не на английском - оторвать руки.

почему?

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

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

не нужны.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Потому что png!

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

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

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

В 1с код на русском

BattleCoder

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

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

SI

В 1с код на русском

необязательно.

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

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

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

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

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

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

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

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

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

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

http://cs10572.userapi.com/u14587137/32738252/y_8995c1c4.jpg

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

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

+100500

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

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

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

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

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

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

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

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

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

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

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

Лорчую :)