Комментировать ли код?

[wind]

Цитата DUKe @ 30.11.06, 21:15

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

Оплошал. Но его нет еще в одном месте.

Сообщение отредактировано: wind - 30.11.06, 21:45

[DUKe]

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

[wind]

Цитата DUKe @ 01.12.06, 09:31

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

Каждой, не каждой - какая разница? В коде (методов) вообще не нужны комментарии.

[Flex Ferrum]

Цитата wind @ 01.12.06, 12:21

В коде (методов) вообще не нужны комментарии.

ИМХО (и не только) ты глубоко ошибаешься. Либо ты пишешь очень тривиальные методы, которым комментарии действительно не нужны.

Добавлено 01.12.06, 12:24
Ибо метод - это конечный результат работы твоей мысли. Он отвечает на вопрос "как делается", но не отвечает на вопрос "почему делается именно так".

[wind]

Цитата Flex Ferrum @ 01.12.06, 12:23

ИМХО (и не только) ты глубоко ошибаешься. Либо ты пишешь очень тривиальные методы, которым комментарии действительно не нужны.

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

А что такое "нетривиальные методы"? Много букв? Или много совершенно неочевидных (из-за невнятных имён) вызовов? Или использован язык, где нету объектов и процедур/функций?

Добавлено 01.12.06, 12:29

Цитата wind @ 01.12.06, 12:27

Ибо метод - это конечный результат работы твоей мысли. Он отвечает на вопрос "как делается", но не отвечает на вопрос "почему делается именно так".

На вопрос "почему" отвечает документация. В моём случае - javadoc. У кого-то еще - отдельный документ. Я уже третий раз повторяю, что имею в виду комментарии языковых конструкций внутри методов (потому что, javadoc пишется на каждый метод).

Скажу больше - вопрос "почему" (или "зачем") - это ко всей программе в целом, а никак не к конкретному методу. Или кто-то скажет, что благодаря комментариям можно нажать чтение кода с произвольного класса/файла проекта и будет понятно, что это за проект?

Сообщение отредактировано: wind - 01.12.06, 12:31

[Flex Ferrum]

Цитата wind @ 01.12.06, 12:27

А что такое "нетривиальные методы"? Много букв? Или много совершенно неочевидных (из-за невнятных имён) вызовов? Или использован язык, где нету объектов и процедур/функций?

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

Добавлено 01.12.06, 12:31

Цитата wind @ 01.12.06, 12:27

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

Ага. И ты в джавадоке будешь расписывать: "Здесь применен такой подход для того, чтобы обойти косяк в такой то библиотеке". Или "такая неочевидная стратегия обработки того-то и того-то применена в целях оптимизации по быстродействию".

[wind]

Цитата Flex Ferrum @ 01.12.06, 12:30

Или "такая неочевидная стратегия обработки того-то и того-то применена в целях оптимизации по быстродействию".

О! Хороший пример. Я пишу на Java. Человек, который пишет на Java должен знать все трики для повышения производительности. Не знает - я учить не нанимался.

Добавлено 01.12.06, 12:33

Цитата wind @ 01.12.06, 12:33

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

Ну, это исключение из правил. Это очень редко приходится писать.

Цитата Flex Ferrum @ 01.12.06, 12:30

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

М-м... так не бывает. Я так думаю и имею основания продолжать оставаться при своём мнении.

Сообщение отредактировано: wind - 01.12.06, 12:35

[Flex Ferrum]

Цитата wind @ 01.12.06, 12:33

Человек, который пишет на Java должен знать все трики для повышения производительности.

Кому это он должен? Тебе что-ли? С какой стати?

[wind]

Цитата Flex Ferrum @ 01.12.06, 12:34

Кому это он должен? Тебе что-ли? С какой стати?

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

Сообщение отредактировано: wind - 01.12.06, 12:37

[Flex Ferrum]

Цитата wind @ 01.12.06, 12:36

Себе должен. Или программист уже ничего не должен знать, чтобы работать?

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

[Бобёр]

Ну, например, у меня есть такой неочевидный метод.

void CMegaClass::myFunc( Tree* tree )
{
  for( int i = 0; i < 8; i++ ) {
    myFunc1( tree );
  }
}

фактически, одна и та же функция вызывается 8 раз. Зачем, спрашивается? Семантика методов прозрачна, действие тоже понятное, однако как ни крути, средствами языка C++ НИКАК не объяснить, змем фукнция вызывается 8 раз с совершенно одинаковыми параметрами? Приходится объяснять словами, что это сделано для того, что бы не усложнять алгоритм функции myFunc1 (он бы стал НУ ОЧЕНЬ нетривиальным, если бы всё делалось за один проход, такая специфика деревянной XML структуры)

Сообщение отредактировано: BugHunter - 01.12.06, 13:38

[DUKe]

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

[Rikkie]

Цитата DUKe @ 01.12.06, 12:48

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

Хотите конкретный пример?
Имеется источник синхронизации. По синхронизации смещаются два счетчика. По превышении порога одним счетчиком стартует процесс №1, по превышению порога вторым счетчиком стартует процесс №2. Приоритеты процессов разные. Процесс №1 передает через некий пайп данные для процесса №2. Для того, чтобы не получилось так, что процесс №1 остался без данных, я смещаю значение счетчика №2 на 90 градусов.

Так вот, через года два-три я взгляну на это дело и задамся вопросом: а нафих я вводил это смещение? Затем посмотрю в комментарии и все станет ясно. А без комментариев я могу напороться на старые задницы, ибо приходится иметь дело с большими объемами информации, и такие мелочи долго в памяти не задерживаются.

[DUKe]

Rikkie, хороший пример. Только я не понял, что он иллюстрирует.

[Rikkie]

Цитата DUKe @ 01.12.06, 12:57

Только я не понял, что он иллюстрирует.

Ключевой момент - смещение счетчика. Почему я это делаю? Такие решения ОДНОЗНАЧНО нужно комментировать.