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

Влад Цепеш был адекватным. Он не мечтал, он сажал.

Кэп-режим: все хорошо, но вмеру.

Как говорил дедушка Кнут:

some of us are glad that traditional programming languages have comparatively primitive capabilities for inserted comments, because such difficulties provide a good excuse for not documenting programs well

Что можно перевести на русский как:

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

Сам Кнут всё же любит описывать что делает программа. Причём описывать подбробно, как в случае rubber duck debugging'а. Вот пример: http://www.literateprogramming.com/knuthweb.pdf

этой фразе 50+ лет ЕМНИП, разве сейчас нельзя комментировать по-русски и вообще, так, как удобно кодеру (и его коллегам)?

этой фразе 50+ лет ЕМНИП, разве сейчас нельзя комментировать по-русски и вообще, так, как удобно кодеру (и его коллегам)?

Ей и 30 лет нету. За последние 30 лет мало что изменилось: комментарии это всё те же блоки символов, выкидываемые лексером при разборе файла. Конечно doxygen/javadoc/etc тут сделали огромный шаг вперед, позволив извлекать из комментариев к коду полноценную документацию, но, как вы видите по этой теме, программисты всё равно не хотят документировать код, потому что в тривиальных случаях документация просто будет повторять сигнатуру метода.

если тяжело понять что и как, то значит код нуждает в рефакторинге.

Литературное программирование, знаем такое, нам все грозились, что заставят так программы писать, но пока случаев небыло.

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

почему?

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

а с этой что не так? как надо вести бух.учет?

Английско-нижегородский лучше, точно.

Не всех, а только преступников )

http://old-rus.narod.ru/06-7.html

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

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

Достоверно известно что разработчику все понятно априори

Сынок, а что ты написал вон в том Perl-скрипте три месяца назад?

ObjC детектед.

Там даже код - частично - можно писать на русском за счет Юникода. )

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

Вообще-то из комментариев как на иллюстрации генерируется потом описание библиотеки в doxygen.

иногда комментарии просто необходимы: http://pastebin.com/ndMGKqpc

Вы мой пост до конца прочитайте =)

ничего против не имею.

Комментарии нужны. Во всех тех местах, где без них неочевидна суть.

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

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

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

Там Java, вообще-то. Причем редактируют ее в Netbeans.

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

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

Ты сразу начал писать идеальную документацию к своему коду? Все мы учимся, хоть и с разной эффективностью. И стройность изложения мыслей приходит с опытом. Как в коде, так и в доках.

если тяжело понять что и как, то значит код нуждает в рефакторинге.

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

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

В конторах, от проекта к проекту, бывает юзают автодокументаторы и обязательно требуют описывать интерфейса для подхвата этой тулзой. Выглядят эти коменты в коде, как высказывания К.О., но, сюрприз-сюрприз, предназначены для чтения не в коде, а в RTFM к бинарю библиотеки, сорцы которой никто показывать никому внезапно не собирается. Так что в твоей иллюстрации примерно такой случай, ничего удивительного, и смысл есть, но другой.

Вы картинку смотрели вообще? Не во всех случаях кто-то пользующийся библиотекой, будет читать ее код. И совсем не обязательно, этот код ему будет доступен. Автокомментарии - чаще всего это болванка для дописывания руками. Если аффтары кода оставили коммент робота без правок - ССЗБ, только и всего.

из названия метода в принципе понятно что он делает

Ни капельки не понятно обычно. Но в данном случае, метод - вырожденный. Он ничего не делает (родовая болезнь J2EE - множество пустых методов из 1-2 строчек). Когда у тебя будет метод строчек хотя бы из пяти, да ещё и с сайд-эффектами, комментарий необходим.

Потому что это не метод, это геттер.

Не всех, а только преступников )

Если мне не изменяет память, он ещё верующих недолюбливал.

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

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

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

man «самодокументирующийся код»

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

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

почему?

Комментарий не на английском

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

почему?

Комментарий не на английском

Не во всех случаях кто-то пользующийся библиотекой, будет читать ее код.

Интерфейс функции должен описывать её работу, а не код реализации.

Вы картинку смотрели вообще?

На картинке - автодок и комментарием является только синтаксически.

Я вот забыл эту часть спецификации, помню только, что трансформации Unicode escapes делается перед всем остальным. Идентификаторы тоже можно?

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

«literate programming» обычно переводят как «грамотное программирование». И кто грозился? Кнут всегда говорил:

If literate programming isn’t your style, please forget it and do what you like. If nobody likes it but me, let it die.

а) Вы уверены, что вы изобрели велосипед? Может есть попроще и эффективнее? б) Каждый сложный алгоритм состоит из последовательности простых действий, каждый из которорых можно воплотить в понятный код.

если не троллил изначально, делая внезапные выводы из заведомо ложной посылки

Ты знал!

Я отвечал на вопрос в заголовке, потому что он показался мне здравым, в отличие от ОПа, который я отфильтровал по вышеприведенной причине.

Можно, но не нужно.

И кто грозился?

Явно не Кнут.

Fuuuu

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

public PeriodChngr getCurChngr ()
	return chngr.load ();

Да, идентификаторы считаются состоящими из «букв Java» и цифр. А все буквы Java представляются Юникодом.

PeriodChngr

getCurChngr

chngr

Ты когда-нибудь слышал о человекочитаемых именах?

return chngr.load ();

Откуда ты взял, что chngr.load() возвращает этого самого chngr?

Ну и еще ты пропустил фигурные скобочки.

PS. Я б убил бы за такой малобукв-быдлокод. А на картинке все правильно, кроме комментариев в стиле КО (но и они уместны, ибо doxygen).

Ну и еще ты пропустил фигурные скобочки.

Для одной команды они не нужны (хотя хз как там у java, в js вроде так).

Откуда ты взял, что chngr.load() возвращает этого самого chngr?

Это да ;) Чудный этот ваш ООП...