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

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

Интересно ваше мнение.

Цитата MIF @ 13.11.06, 13:28

Я никогда не пишу комментарии к своему коду. Я считаю это занятие пустой потерей времени.

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

Цитата MIF @ 13.11.06, 13:28

Они замедляут меня, т.к повторяют то, что написано в коде.

Это неправильные комментарии.

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

Цитата MIF @ 13.11.06, 13:28

Я никогда не пишу комментарии к своему коду. Я считаю это занятие пустой потерей времени.

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

Цитата MIF @ 13.11.06, 13:28

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

Ну-ну... Я думаю, надо примеры кода приводить для наглядности.

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

int AxisData::GetPosInv( double Value )
{  
    if ( Logarithmic )
    {
        if ( Value == 0 )
            return (int)(fabs(log10(Min))/Scale);
        else
            return (int)((log10(Max)-log10(Value))/Scale);
    }
    else
        return ( (int)((Max - Value)/Scale) );
}

Сообщение отредактировано: Nich - 13.11.06, 13:44

Цитата Medevic @ 13.11.06, 13:30

Цитата MIF @ 13.11.06, 13:28

Я никогда не пишу комментарии к своему коду. Я считаю это занятие пустой потерей времени.

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

Цитата MIF @ 13.11.06, 13:28

Они замедляут меня, т.к повторяют то, что написано в коде.

Это неправильные комментарии.

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

//это переменная типа int. длйы начала она инициилизируется на 0
int i=0;

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

Добавлено 13.11.06, 13:43
кстати, не только для других надо комментировать: гляньте в свой код 4-х летней давности, например. неужели все так понятно с лету?

Цитата nastenka @ 13.11.06, 13:42

кстати, не только для других надо комментировать:

Цитата nastenka @ 13.11.06, 13:42

гляньте в свой код 4-х летней давности, например. неужели все так понятно с лету?

Мой код 4-летней давности это ваще жесть Ща ссылку кину на примерчик.

Символьное дифференцирование Без комментариев там бы вообще атас был бы

Добавлено 13.11.06, 13:54
Такие комментарии, конечно, излишние:

tree_elem() // Конструктор структуры - присваивает начальные значения

Сообщение отредактировано: Nich - 13.11.06, 13:54

Цитата Nich @ 13.11.06, 13:37

Сколько надо времени, чтобы понять, что делает эта функция?

Вернуть отмаштабированное расстояние от максимально допустимого значения. Использовать логарифмическую формулу (с исключением при входном параметер = 0) либо линейную в зависимости от значения глобальной (модульной) переменной.
Сколько времени - засекать не стал, т.к. сейчас поздний вечер и я подштофе, производительность мозга невелика.

Цитата nastenka @ 13.11.06, 13:42

вот когда перед функцией написана строчка-две, что она (функция) делает - это толково

Имя функции должно обяснять, что она делает.

Цитата nastenka @ 13.11.06, 13:42

гляньте в свой код 4-х летней давности, например. неужели все так понятно с лету?

Да.

Цитата MIF @ 13.11.06, 13:57

Сколько времени - засекать не стал

Ну так это же ключевой момент

Цитата Nich @ 13.11.06, 14:02

Ну так это же ключевой момент

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

Кстати, тест некорректен. Я утверждаю, что читаю код без комментов быстрее, чем код с комментариями. Выложи два куска кода одинаковой сложности, один с комментариями, другой - без них ...

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

Очень распространено, например, следующее явление

//++ 10.10.2005 by SeaGirl
//Добавлена проверка и отображение украденных счетчиков
//Согласно письму №ХХХ-ХХ от такой-то даты
 
if CountersQuery.FieldByName('Status').AsInteger=10 then
...

Иногда еще в комментариях разработчики могут обменяться впечатлениями о заказчике

Цитата MIF @ 13.11.06, 13:57

Имя функции должно обяснять, что она делает.

угу, и что она в каком случае возвращает - тоже имя должно делать? ну-ну

я ЗА комменты, при чем грамотные
Вот неправильный

Цитата

а=1;//Присваиваем а 1

это правильные комменты

Цитата

//Проходим по всей колекции для подсчета тогото и сегото
for i = 0 to object.length()-1 do
...
...
loop

return true; //заглушка

кстати такие коменты намного ускоряют чтение кода можно пропускать целые секции...

Сообщение отредактировано: Outlander - 13.11.06, 15:05

Цитата

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

но естественно смысловые комментарии..

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

Цитата MIF @ 13.11.06, 13:28

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

а если пользуешься чужой библиотекой и у тебя нет спецификации на нее

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

потом, смотря какого типа язык
ИМХО ООП - более понятен для человека, нежели процедурный

Цитата MIF @ 13.11.06, 13:57

Имя функции должно обяснять, что она делает.

обязательно , как и имена переменных, и названия типов данных
но вот

Цитата nastenka @ 13.11.06, 14:56

и что она в каком случае возвращает

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

Про то, что возвращает функция.
Я даже знаю, что скажет скептический MIF на это.
Можно ведь константами задать значения, которые может возвращать функция, дать этим константам понятные имена и вуаля. Но комментарии все равно необходимы.

MIF, кстати, а часто ты сам работаешь с чужим кодом? или работаешь ли в комманде, когда над одним кодом несколько (много и все разные) специалистов работают?

Лучший коммент, который я видел (АСУТП, SCADA)

// Транспорт внезапно уехал :(

Цитата nastenka @ 13.11.06, 15:25

MIF, кстати, а часто ты сам работаешь с чужим кодом? или работаешь ли в комманде, когда над одним кодом несколько (много и все разные) специалистов работают?

тут скорее важен не сколько факт работы с чужим кодом
а его(чужого) объемы

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

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

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

Цитата BugHunter @ 13.11.06, 16:47

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

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

/*
 * Переменная для хранения числа элементов в контейнере.
 */
private int elementCount;

Одно только комментирование замедляет в три-пять раз. Не буду ничего говорить о тестах

Сообщение отредактировано: wind - 13.11.06, 17:53

Цитата SeaGirl @ 13.11.06, 15:23

Про то, что возвращает функция.
Я даже знаю, что скажет скептический MIF на это.
Можно ведь константами задать значения, которые может возвращать функция, дать этим константам понятные имена и вуаля

SeaGirl, не понял идеи. Поподробнее можно?

Цитата nastenka @ 13.11.06, 15:25

кстати, а часто ты сам работаешь с чужим кодом?

Примерно десять процентов моего рабочего времени.

Цитата nastenka @ 13.11.06, 15:25

или работаешь ли в комманде, когда над одним кодом несколько (много и все разные) специалистов работают?

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

МИФ, просто тогда ты не в любой фирме сможешь работать. У меня, например, большинство проэктов - коммандные и только небольшая часть то, что я делаю оодна. И кстати, нет гарантии, что тот или иной проект будет продолжать кто-то другой. не писать комментарии - это еще и неуважение к коллегам. А если они тее смаому мешают - их можно складывать (есть массы эдиторов, которые это умеют)

Цитата MIF @ 14.11.06, 09:19

SeaGirl, не понял идеи. Поподробнее можно?

type
  TFunctionResultType = (frtRight, frtWrong, frtOther);
 
function ReturnSomeResult: TFunctionResultType;

Smike, спасибо.
Комментарии читал-читал - ничего не понял. Код прочитал - все понятно, хотя на Дельфи(?) не программирую.

Цитата MIF @ 14.11.06, 10:07

Комментарии читал-читал - ничего не понял.

Это ты к чему?

Цитата MIF @ 14.11.06, 10:07

хотя на Дельфи(?) не программирую.

А какая разница на чем ты программируешь? Я на С не пишу, но код прочесть могу. Тут вобще дело не в том языке, на котором ты работаешь.

Цитата MIF @ 14.11.06, 09:19

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

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

Цитата SeaGirl @ 14.11.06, 10:49

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

Более того - я комментарий пишу раньше кода ! И это правильно, т.к. написав комментарий становится более ясно, как же назвать переменную, функцию и т.п.

Цитата

Одно только комментирование замедляет в три-пять раз.

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

Добавлено 14.11.06, 10:56

Цитата

Я например не могу выбирать самой мне писать программу или нет.

Что либо действительно большое и полезное в одиночку не осилить.

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

А вот язык Форт способствует (если не сказать навязывает) написанию самодокументирующего кода.

К сожалению, далеко не любой код (даже написанный красиво) не может быть самодокументируемым. Точнее, он очень редко может быть таковым. А именно - только в том случае, если является самодостаточным. Если в коде используются сторонние компоненты, или это фрагмент большой системы, то комментарии нужны. Иначе, как бы ни был красиво и понятно написан данный конкретный фрагмент кода, читающий его должен будет потратить немало времени в изучении документации к компонентам, которые этот код использует. Ну, вот пример. Сейчас пришу серверные контролы для ASP.NET. Для того, чтобы понять механизм работы серверного контрола надо очень долго и нудно курить MSDN. И все равно что-то останется за кадром. Может ли быть такой код самодокументируемым?

Добавлено 14.11.06, 11:47
В случае разработки больших систем аналогично. Далеко не всегда у программиста может быть достаточно времени/возможностей на изучение того, что и как делают используемые в коде компоненты. А потому - зачем усложнять ему жизнь?

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

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

Цитата wormball @ 14.11.06, 11:26

А вот язык Форт способствует (если не сказать навязывает) написанию самодокументирующего кода.

это миф

Цитата BugHunter @ 14.11.06, 13:13

это миф

Это почему?

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

А у нас не пишут комментариев, разбирайся как хочешь. А вот если комментарий все таки появился, то скорее всего он будет написан большими буквами и смысл его передается одним словом:
// П@#$Ц!!!!!!!!

Цитата nastenka @ 14.11.06, 13:40

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

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

Кстати, описания входных и выходных параметров как таковые в Форте не нужны, поэтому их как раз делают в форме комментариев.

Цитата wormball @ 14.11.06, 15:45

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

Ну так так предлагается делать не только в форте. Но проблемы то это не решает.

Цитата Flex Ferrum @ 14.11.06, 16:07

Ну так так предлагается делать не только в форте.

Зато в форте это навязывается. Ибо без этого на нём шиш напишешь что-либо серьёзнее, чем "Превед, Мяуд!" "Hello, World!".

Цитата wormball @ 14.11.06, 16:53

Зато в форте это навязывается. Ибо без этого на нём шиш напишешь что-либо серьёзнее, чем "Превед, Мяуд!" "Hello, World!".

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

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

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

Цитата wormball @ 14.11.06, 17:02

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

Он конечно остаётся самодокументированным. До поры до времени. И в С++ е такая же фигня. Кучка маленьких осмысленных функций. А вот когда соберут их купно - тут уже держись

Добавлено 14.11.06, 17:22
..и потом, что значит "навязывает"? Програмеру всё равно никто не помешает назвать свою мега функцию
OopsIDidItAgain24()

Цитата SeaGirl @ 14.11.06, 17:06

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

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

Цитата BugHunter @ 14.11.06, 17:18

Он конечно остаётся самодокументированным. До поры до времени. И в С++ е такая же фигня. Кучка маленьких осмысленных функций. А вот когда соберут их купно - тут уже держись

Идеального языка, как мы уже выяснили, не существует.

Цитата BugHunter @ 14.11.06, 10:55

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

Правда?
Я бью 300-350 знаков в минуту. На кириллице. На латинице побыстрей Всё хочу обучиться слепому десятипальцевому. Но потеря времени на лицо. Я кодирую, отражая свои мысли; могу нарисовать полсотни классов (к счастью, сразу не документирую), грохнуть, еще полсотни нарисовать.

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

Цитата wind @ 14.11.06, 20:27

Я бью 300-350 знаков в минуту. На кирилице. На латинице побыстрей Всё хочу обучиться слепому десятипальцевому.

Ты хочешь сказать, что набиваешь 300 знаков в минуту не используя слепой 10-пальцевый??? Это через телепатический интерфейс чтоли?

Цитата Relan @ 14.11.06, 20:33

Ты хочешь сказать, что набиваешь 300 знаков в минуту не используя слепой 10-пальцевый??? Это через телепатический интерфейс чтоли?

А что, всё так сложно? Упорные тренировки всегда дают результат

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

Лично я без комментариев не могу !!! Бывают ситуации когда допустим забыл про прогу и вдруг понадобилось что-то посмотреть как там делал , без комментариев можно и не понять!!! Комментарии - отличная вещь.

весь тред пока ниасилил, так что пока только по сабжу:

комментирую код в разумных пределах.
перед функцией - (или на перевой строке функции, сразу после объявления) - три - пять строк каммента, поясняющих, что эта за функция, что она делает, что возвращает и какие параметры принимает. При необходимости - специфичные камменты, например "в случае некорректных параметров возвращает -1" или "возвращает ошибку Illegall Function Call, если параметры некорректны."

комментирую глобальные переменные, поясняя, для чего они нужны и что именно в них хранится. (невсегда, только если область её видимости настолько велика, что невозможно понять её назначение за 20-30 секунд.)

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

когда правлю чужой код - обязательно помечаю начало и конец "блока исправлений", используя стандартную для всего проекта сигнатуру, например "//F_BS ". это чтоб потом легко находить свои исправления. Также сохраняю оригинальную версию блока исправлений, просто закрываю его знаками каммента. очень помогает потом вспомнить, зачем я внёс изменения, и убедиться, что это не зря

Цитата wormball @ 14.11.06, 18:12

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

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

Цитата SeaGirl @ 15.11.06, 06:36

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

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

Цитата SeaGirl @ 15.11.06, 06:36

Или ты хочешь сказать, что если ты даешь этим функциям правильные имена, то это избавляет от нормального комментирования?

Я этого не говорил. Более того, всё хочу свой форт откомментировать, только руки не доходят.

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

Цитата wind @ 13.11.06, 17:52

Одно только комментирование замедляет в три-пять раз.

Замедляет что? Написание!

Но код в 10 раз чаще читается, чем пишется. Пишется-то один раз по большому счёту. Подумай над этим

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

Цитата Flex Ferrum @ 22.11.06, 08:50

Вообще не раз замечал, что начав комментировать код тут же находишь в этом коде ошибки или неточности.

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

Цитата Flex Ferrum @ 22.11.06, 08:50

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

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

Сообщение отредактировано: BugHunter - 22.11.06, 19:15

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

Коментареи вещь сильная.. особенно понял это в IнтеракивномDизAссемблере... Очень помогает.. Особенно в борьбе с обьектно-событийным кодом, навроде WndProc/DlgProc, триад или каких нибудь таймерных обработчиков тиков..
А так - самом начале очерчиваю общий план работы, ну и список "функционала" с которыми предстоит детальная "работа".

Цитата rvt @ 22.11.06, 08:27

Замедляет что? Написание!

Но код в 10 раз чаще читается, чем пишется. Пишется-то один раз по большому счёту. Подумай над этим

Читается кем? Если не мной, то не всё ли мне равно?

Цитата

Читается кем? Если не мной, то не всё ли мне равно?

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

Цитата BugHunter @ 23.11.06, 16:02

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

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

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

Я всё время забываю, что не все в курсе по поводу комментариев, которые я имею в виду. Помимо комментариев в коде это еще и комментарии для генерации документации. Но предыдущая пара сообщений про обычные комментарии. А для разминки следующее:

// ?
int multiply(int i, int j) {
    // ?
    return i * j;
}

Теперь вопрос на засыпку - что мне писать в комментариях вместо знаков вопроса?

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

Цитата wind @ 27.11.06, 08:17

Теперь вопрос на засыпку - что мне писать в комментариях вместо знаков вопроса?

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

wind, есть мнение, что ты и более сложный код пишешь)

Цитата wind @ 27.11.06, 08:17

Теперь вопрос на засыпку - что мне писать в комментариях вместо знаков вопроса?

Например, так:

// Умножение объявлено в виде отдельной функции,
// потому что используются делегаты, а в языке нету анонимных функций и лямбд
int multiply(int i, int j) {
    return i * j;
}

Цитата mo3r @ 27.11.06, 15:24

// потому что используются делегаты, а в языке нету анонимных функций и лямбд

boost::lambda...

Цитата Flex Ferrum @ 27.11.06, 15:37

boost::lambda...

wind использовал CODE=JS

Цитата Smike @ 27.11.06, 15:49

wind использовал CODE=JS

В JS есть анонимные функции (да и лямбды, вроде бы, тоже есть).
Например, для C этот комментарий вполне нормален.

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

Цитата Flex Ferrum @ 27.11.06, 15:37

boost::lambda...

Знаю про это

Цитата Nich @ 27.11.06, 10:26

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

Цитата DUKe @ 27.11.06, 14:33

wind, есть мнение, что ты и более сложный код пишешь)

Господа, успокойтесь, нет никакой ложки Наименование функции в примере не имеет значения, равно как и действия совершаемые внутри. Смысл в том, что нормально написанный код в комментариях не нуждается.

Цитата mo3r @ 27.11.06, 16:07

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

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

Цитата Smike @ 27.11.06, 15:49

wind использовал CODE=JS

Потому как нету CODE=JAVA. Но это тоже неважно, можно считать, что пример на псевдокоде.

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

Цитата wind @ 27.11.06, 17:42

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

Смотря что считать комментариями. ТЗ, полная техническая документация и юнит тесты вполне сойдут за комментарии.

Цитата wind @ 27.11.06, 17:42

Больше того, я никогда не стану указывать в коде почему поступил так, а не иначе - кому надо и так поймет, остальные - в сад

Если этот код попадет ко мне, то угадай, кто и куда пойдет

Цитата wind @ 27.11.06, 17:42

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

В сад тех, кто так пишет код.

Цитата Relan @ 27.11.06, 21:04

В сад тех, кто так пишет код.

Там и встретимся

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

Добавлено 27.11.06, 22:38

Цитата mo3r @ 27.11.06, 18:15

Смотря что считать комментариями.

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

Цитата wind @ 27.11.06, 22:37

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

С этим согласен по всем параметрам! ++

Цитата wind @ 27.11.06, 22:37

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

А вот я не совсем согласный. Ибо:
1. Твой преемник может знать язык и платформу на другом уровне (или другие его аспекты).
2. Твой преемник не сможет залезть в твою голову и посмотреть - какие же процессы там проходили, когда ты писал тот или иной фрагмент кода. А потому не сможет понять - почему именно ты принял такое решение.
3. Будучи реалистом могу сказать, что код, который переходит на поддержку, не страдает чистотой, особенно если он активно "докручивался". И начиная с некоторого момента за костылями не видно первоначальной идеи.
4. Всегда останутся неочевидные вещи, которые были известны автору (из разговоров, обсуждений с коллегами, заказчиком и т. п.), в итоге нашли свое отражение в коде, но иным образом нигде не зафиксированные, а потому преемник о них ничего не знает.
Ну например, стоит у тебя в коде некоторое условие. Читаешь спеки - условия быть не должно. А оно есть, и все правильно работает. Через какое-то время может выяснится, что условие попало в код из за того, что действительность спекам соответствует не во всем, и условие просто необходимо.

Цитата

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

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

Цитата BugHunter @ 28.11.06, 10:07

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

Участвовал и участвую.

Цитата wind @ 28.11.06, 12:13

Участвовал и участвую.

"Какие ваши доказательства?"

Кстати, иногда удобнее дать переменной имя попроще, чтобы сократить размер текста. Натыкался как-то на пример, где переменные имели имена что-то вроде 'Средняя_скорость_падения_капли' (в переводе на русский). Понять текст программы было практически невозможно, каждое выражение занимало несколько строк.

для локальный переменных длинные имена не оправданы, но чем больше область видимости - тем имя обязано быть длиннее (т.е. понятнее вдали от места её объявления)

Просто иногда, к счастью редко, стремление к понятности доходит до идиотизма. Можно было просто назвать переменную v_avg (v_average) и пояснить комментарием, что она содержит.

Цитата amk @ 29.11.06, 15:07

Можно было просто назвать переменную v_avg (v_average) и пояснить комментарием, что она содержит.

Не очень удачное название, ибо очень похоже на v_arg.

Цитата wind @ 27.11.06, 22:37

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

За одного такого, было дело, приходилось заново проект переписывать.

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

Цитата Rikkie @ 29.11.06, 15:59

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

"Коллег", которые не в состоянии понять код (где нет, кстати, непонятных имен) не уважу даже пренебрежительным отношением. Буду давить

А переписывать проект в силу незнания предмета - это что-то новенькое

Сообщение отредактировано: wind - 29.11.06, 19:32

Цитата amk @ 29.11.06, 15:07

Просто иногда, к счастью редко, стремление к понятности доходит до идиотизма. Можно было просто назвать переменную v_avg (v_average) и пояснить комментарием, что она содержит.

Не очень хорошее название.
Само по себе слокращение avg общепринятое, и что то вроде avgSpeed (speed - к примеру только) было бы понятнее.
А то - что среднее? Расстояние между ушами зайцев?
Хотя и от averageSpeed при нынешнем автодополнении IDE никто бы не умер.
И потом, представьте, что вы участвуете в аутсорсинг проекте.
Ничего нет хуже, чем читать английский комментарий не-резидента англоговорящей страны
Разве что Петросян. По крайней мере такие комментарии смешнее.
Лучше уж понятное название переменной дать.

Цитата wind @ 29.11.06, 19:29

"Коллег", которые не в состоянии понять код (где нет, кстати, непонятных имен) не уважу даже пренебрежительным отношением. Буду давить

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

Сообщение отредактировано: Evil J - 29.11.06, 19:41

Цитата wind @ 29.11.06, 19:29

"Коллег", которые не в состоянии понять код (где нет, кстати, непонятных имен) не уважу даже пренебрежительным отношением. Буду давить

Считаю аналогично. И приведу тому пример.

Взять хотя бы те же исходники VCL или JVCL, и многих других проектов с открытым исходным кодом. Комментарии там достаточно редкий гость, обычно только комментируются обходы багов, чтобы было понятно, для чего вплетена та или иная глупость. И это правильно. Обычно большего и не нужно. Я обычно легко вникаю в чужой код, даже без комментариев (если он конечно более-менее нормально оформлен, а не по одной строке вместо трех, без выделения функциональных блоков...).

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

Цитата Evil J @ 29.11.06, 19:37

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

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

Цитата Nich @ 29.11.06, 19:50

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

Вы еще не придумали комментарии для моего маленького примера.

Цитата wind @ 29.11.06, 20:37

Вы еще не придумали комментарии для моего маленького примера.

Комментировать ли код? (сообщение #1357726)

Цитата Nich @ 29.11.06, 20:45

Комментировать ли код? (сообщение #1357726)

Я на всякий случай воспользовался magnifier'ом и рассмотрел ник автора сообщения. Не ваш.
А тот комментарий авторитетной комиссией в моём лице не принимается. Он никак не поясняет код.

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

Цитата wind @ 29.11.06, 20:49

Я на всякий случай воспользовался magnifier'ом и рассмотрел ник автора сообщения. Не ваш.

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

Цитата wind @ 29.11.06, 20:49

А тот комментарий высосан из пальца и авторитетной комиссией в моём лице не принимается. Он никак не поясняет код.

У Вас, как я понимаю, очень высокое самомнение. Может быть тогда сами поясните свой код? Или это уже будет стоить денег?

Сообщение отредактировано: Nich - 29.11.06, 21:29

Цитата Nich @ 29.11.06, 21:28

Может быть тогда сами поясните свой код? Или это уже будет стоить денег?

Зачем? Пример иллюстрирует абсолютную неуместность каких-либо комментариев.

А вы... как бы это сказать... очень предсказуемы

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

Цитата

А вы... как бы это сказать... очень предсказуемы

Кхгм. Давно я не писал легко предсказуемый код. Видимо, задачки виноваты. А куда деваться - все простые задачки на умножение уже решены (да и не люблю я умножать, я люблю отнимать и делить), остались те, что посложнее - факториалы и др. числа Фибоначчи

Цитата wind @ 29.11.06, 19:29

"Коллег", которые не в состоянии понять код (где нет, кстати, непонятных имен) не уважу даже пренебрежительным отношением.

Замечательно. Теперь ситуацию рассмотрим: передается тебе на поддержку приличненький проект, в котором используется множество паттернов, уяттернов, в общем достаточно много наворотов. Общая цель известна, но детали реализации - тут надо разбираться. Далее: заказчик говорит, что ту или иную фичу нужно переделать (вполне нормальная ситуация). Сколько тебе времени понадобится, чтобы разобраться где эта фича реализована, как она работает etc?
Уверен, что если код был бы нормально комментирован (не просто тупо комментарии типа // присваиваем а значение б, а нормальные комментарии типа класс такой-то предназначен для того-то имеет такие-то особенности, метод класса реализует алгоритм такой-то), было бы намного быстрее. А время - деньги. Смотри, как бы тебя не задавили.

Цитата wind @ 29.11.06, 19:29

А переписывать проект в силу незнания предмета - это что-то новенькое

Это ты мне в упрек ставишь? И почему ты решил, что причина именно в незнании предмета?

Проиллюстрирую свою позицию. Такой код и с комментариями не разберешь:

Procedure TMCoPShadowButton.CreateShadow;
var
 p,l,t:pbytearray;
 w,h,x,y,k:integer;
 q,u,e,r,g,b:Byte;
begin
if fTraMo=tmAuto then fTrans:=fImg.Canvas.Pixels[0,fImg.Height-1];
fImg.Transparent:=True;
fImg.TransparentColor:=fTrans;
r:=getrvalue(fFore);
g:=getgvalue(fFore);
b:=getbvalue(fFore);
q:=getrvalue(fBack);
u:=getgvalue(fBack);
e:=getbvalue(fBack);
fImg.PixelFormat:=pf24bit;
fShd.PixelFormat:=pf24bit;
w:=fImg.Width+4;
h:=fImg.Height+4;
p:=allocmem(w*h);
fillmemory(p,h*w,0);
for y:=0 to fImg.Height-1 do
 begin
 l:=fImg.ScanLine[y];
 for x:=0 to fImg.Width-1 do
  if TColor(rgb(l^[x*3+2],l^[x*3+1],l^[x*3]))<>fTrans then
   p^[(x+2)*h+y+2]:=fAlpha;
 end;
t:=allocmem(w*h);
fillmemory(t,h*w,0);
for x:=1 to w-2 do
 for y:=1 to h-2 do
  begin
  k:=p^[x*h+y];
  k:=k+p^[(x-1)*h+y-1];
  k:=k+p^[(x-1)*h+y];
  k:=k+p^[(x-1)*h+y+1];
  k:=k+p^[x*h+y+1];
  k:=k+p^[(x+1)*h+y+1];
  k:=k+p^[(x+1)*h+y];
  k:=k+p^[(x+1)*h+y-1];
  k:=k+p^[x*h+y-1];
  t^[x*h+y]:=k div 9;
  end;
freemem(p);
fShd.Width:=w;
fShd.Height:=h;
for y:=0 to h-1 do
 begin
 l:=fShd.ScanLine[y];
 for x:=0 to w-1 do
  begin
  l^[x*3+2]:=(r*t^[x*h+y]+q*(255-t^[x*h+y])) div 255;
  l^[x*3+1]:=(g*t^[x*h+y]+u*(255-t^[x*h+y])) div 255;
  l^[x*3  ]:=(b*t^[x*h+y]+e*(255-t^[x*h+y])) div 255;
  end;
 end;
freemem(t);
end;

Добавлено 30.11.06, 11:47

Цитата Rikkie @ 30.11.06, 11:37

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

Ну это уже не комментирование, а документирование.

Цитата Smike @ 30.11.06, 11:46

Ну это уже не комментирование, а документирование.

Это смотря где описано.

Цитата Smike @ 30.11.06, 11:46

Такой код и с комментариями не разберешь:

С комментарием о том, что тут происходит, и разбирать, возможно, ничего не придётся.

Цитата Smike @ 30.11.06, 11:46

Ну это уже не комментирование, а документирование.

Ну пускай будет документирование. Это по сути что-то меняет?

Цитата

Такой код и с комментариями не разберешь

Цитата

-Слушай, ну зачем так хорошо одеваться? По одёжке встречают, по уму провожают.
-Дарагой, а что плохого в том, если нас и встретят, и проводят хорошо?

(не помню откуда)

Цитата

-Слушай, зачем комментировать хороший код?
-Дарагой, а что плохого в том, если хороший код будет ещё и закомментирован хорошо?

(Я)

Комментарии - это средство упорядочения мыслей у читателя кода и (самое главное) - у писателя.

Сообщение отредактировано: BugHunter - 30.11.06, 12:59

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

Цитата Smike @ 30.11.06, 11:46

Проиллюстрирую свою позицию. Такой код и с комментариями не разберешь:

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

Цитата DUKe @ 30.11.06, 17:17

wind, вопрос на засыпку: ты никогда не пользуешься джавадоком

Цитата Smike @ 30.11.06, 11:46

Ну это уже не комментирование, а документирование.

Думаю, что последняя цитата тут уместна, хотя Smike писал эту фразу совсем по другому поводу.

Evil J, ну, знаешь я никаких комментариев кроме джавадока не пишу, но вполне считаю это комментированием. Комментарии это все, что внутри /* */ и после // (ну, или другие варианты для ругих языков)

Сообщение отредактировано: DUKe - 30.11.06, 17:56

Цитата DUKe @ 30.11.06, 17:17

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

Частенько бывало. Но вообще хорошо бы прочитать мои более ранние посты, где я говорил о том, что имею в виду не javadoc (от которого я избавиться никак не могу), а поясняющие комментарии в коде методов. Javadoc - это документация к API, а не комментарии.

Больше того, я, как и автор темы, просто пропускаю комментарии при чтении - они только мешают.

Цитата BugHunter @ 30.11.06, 09:48

Кхгм. Давно я не писал легко предсказуемый код. <...>

Я имел в виду реакцию г-на Nich, разумеется.

Цитата BugHunter @ 30.11.06, 12:57

Комментарии - это средство упорядочения мыслей у читателя кода и (самое главное) - у писателя.

Вот уж точно нет. Сплошной беспорядок. Особенно после очередного некислого рефакторинга

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

у меня после некислого рефакторинга количество комментариев обычно СИЛЬНО увеличивается

Цитата BugHunter @ 30.11.06, 19:45

у меня после некислого рефакторинга количество комментариев обычно СИЛЬНО увеличивается

У меня обычно наоборот — уменьшается.

Цитата wind @ 30.11.06, 19:29

а поясняющие комментарии в коде методов.

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

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

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

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

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

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

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

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

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

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

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

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

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

Цитата 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

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

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

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

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

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

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

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

Цитата 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

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

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

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

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

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

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

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

Цитата 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

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

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

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

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

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

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

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

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

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

Цитата Rikkie @ 01.12.06, 12:50

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

Это еще раз подтверждает, что комментировать нужно неочевидные вещи. Все тривиальные возможности языка/библиотек в комментировании не особо нуждаются. Еща раз ставлю акцент на слове комментирование, а не документирование, которое предполагает комментирование назначения функции и её параметров.

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

Цитата Rikkie @ 01.12.06, 13:25

это будет комментированием или документированием?

Смотря что писать. Если например "получение чисел Фибоначчи рекурсивным методом", – это документирование. Если "Получение копии экрана с использованием функций WinApi. Получаем контекст экрана с помощью GetDC и копируем изображение с него функцией BitBlt." - это комментирование, но практически бесполезное.

Цитата Smike @ 01.12.06, 13:41

Смотря что писать. Если например "получение чисел Фибоначчи рекурсивным методом", – это документирование. Если "Получение копии экрана с использованием функций WinApi. Получаем контекст экрана с помощью GetDC и копируем изображение с него функцией BitBlt." - это комментирование, но практически бесполезное.

Хм... а более формальные определения можешь дать?

Очень просто.

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

Комментирование – это все остальное, что пишется в коде

Хорошо, а теперь, пожалуйста, ответ на мой вопрос.

Так-с... ясно... тут все понимают предмет спора по-своему Продолжать в том же духе бесполезно.

Цитата Smike @ 01.12.06, 13:41

Смотря что писать. Если например "получение чисел Фибоначчи рекурсивным методом", – это документирование. Если "Получение копии экрана с использованием функций WinApi. Получаем контекст экрана с помощью GetDC и копируем изображение с него функцией BitBlt." - это комментирование, но практически бесполезное.

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

Цитата Smike @ 01.12.06, 13:57

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

Я это вижу так:
Документирование - это описание интерфейсов (в общепрограммистском и даже общеинженерном, наверно, смысле этого слова, а не по пповоду ключевых слов interface и т.п.).

Комментирование - все остальное, связанное с символами комментариев текущего языка, кроме закоментированных с целью отладки, либо в иных целях блоков кода. (ПДД я сегодня сдавал, отсюда и такие формулировки)

Цитата Evil J @ 01.12.06, 17:31

(ПДД я сегодня сдавал, отсюда и такие формулировки)

сдал?

Цитата BugHunter @ 01.12.06, 12:46

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

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

Вот уж действительно неочевидный - myFunc, myFunc1, CMegaClass, магическое число... Я конечно, понимаю, - всего лишь пример, но пример знаковый Тут без комментариев, конечно, не обойтись. Хотя, если будут использованы такие имена, то и в комментариях окажется нечто подобное Короче, за такой код сразу секир башка.

Ну хорошо, допустим, вместо имеющих место имен я увижу что-то донельзя информативное. Почему это я вдруг не смогу понять что происходит? Метод myFunc1 будет называться "плюнуть_в_морду" а на самом деле будет инициировать плевок в лысину? Я в силу каких-то причин не смогу посмотреть на метод myFunc1? Или понять, где тот хранит состояние? Или, если увидев, что он взаимодействует только с локальными переменными, не пойму, что написанное - просто галиматья?

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

Я лично в этом примере не вижу, почему цик нельзя загнать внутрь метода MyFunc1. Вдруг иногда можно обойтись меньшим количеством повторов? Не зная деталей того, что внутри MyFunc1 делается (а формально в этом месте ничего и не должно быть известно) уменьшить это количество нельзя. Или может быть это всего лишь обертка для 8 вызовов другого метода. Тогда его лучше было назвать, например, MyFunc1_8_times.

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

сдал?

Сдал)

Цитата

Я лично в этом примере не вижу, почему цик нельзя загнать внутрь метода MyFunc1

В самом методе будет ещё хуже - глазом будет незаметно при беглом осмотре, что переменная цикла i нигде не используется в теле цикла.

Цитата

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

Да, конечно можно. Чаще всего можно. Но тут есть некий геморой: если всё расписывать в одном цикле, то его читаемость будет не на высоте. Аналогию можно привести простую:
-сортировка пузырьком
-быстрая сортировка

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

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

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

Примерно это и написано в комментарии - что бы читатель в случае чего не удивлялся

Цитата

Вот уж действительно неочевидный - myFunc, myFunc1, CMegaClass, магическое число... Я конечно, понимаю, - всего лишь пример, но пример знаковый Тут без комментариев, конечно, не обойтись. Хотя, если будут использованы такие имена, то и в комментариях окажется нечто подобное Короче, за такой код сразу секир башка.

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

Документировать надо каждый серьёзный кусок кода, комментировать - то, над чем хоть чуть задумался, когда писал. Не факт, что будешь регулярно потом использовать, а возврат будет болезненным и, скорее всего, побудит желание переписать всё к лешему.
Блин, когда только изучал всё, написал для отца калькулятор в Дельфи. Язык несложный, но учитывая несколько тысяч строк кода и объявление переменных в начале:

var
40 переменных : integer;
20 переменных : float;
...
Булевых тоже немало использовал.

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

Цитата lava @ 04.12.06, 11:39

В общем, осознаю, что проще будет проект заново на Си разработать

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

Цитата lava @ 04.12.06, 11:39

40 переменных : integer; 20 переменных : float;

Цитата

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

+1
Метод длиннее 30-35-40 строчек - нонсенс, должен настораживать (это тоже желательно отдельно прокомментировать, если в этом ЕСТЬ НЕОБХОДИМОСТЬ), а тут одно только объявление переменных столько занимает.

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

Цитата BugHunter, 03.12.2006, 14:21:14, 1363943

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

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

Цитата Змей(Чёрный) @ 04.12.06, 22:19

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

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

Цитата

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

Ага, кажись аналогия пошла в народ

Цитата

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

Хм, а вот тут уже бывает по всякому. Тут уже возможно нужно какой нибуть hash_map использовать, или т.п.

По-моему гораздо эффективнее использовать функции сортировки стандартных библиотек.
Или тут все программисты-математики с академическим уклоном собрались?
Заняться что ли нечем на проекте будет, еще сортировку писать...

Цитата BugHunter @ 05.12.06, 09:05

Хм, а вот тут уже бывает по всякому. Тут уже возможно нужно какой нибуть hash_map использовать, или т.п.

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

Цитата

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

Бывает по разному.

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

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