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

Я в процессе работы разработал такой вот стандарт комментирования:

Комментарий к методу/функции должен быть в творительном падеже — ибо метод/функция обычно не "вещь в себе", а по принципам ООП определенное результативное действие. Соответственно и комментарий должен описывать её в виде волеизьявления: "Нарисовать дугу на битмапе".

Один комментарий внутри метода, описывающий логику работы метода как длительное действие — "Рисование дуги на битмапе" (так называемая точка входа).

Отдельный комментарий на каждое логически весомое действие в коде в формате длительного действия — "Запись информации в файл" (так называемая точка действия).

Отдельный комментарий на каждое нестандартное, логически непрозрачное место в коде (пометка NB). Должен быть написан таким образом, что бы обратить внимание на эту непрозрачность и максимально её устранить.

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

Получается следующая картина:

// Заполнить шаблон строками из вектора(точки подстановки %)
string Format(string strTemplate, vector<string> stvParams, bool removeFormatSymbs)
{
    //IP Заполнение шаблона строками из вектора(точки подстановки %)

    string strRet;
    int iParamIdx = 0;
    int iParamPos = 0;
    //NB Последняя точка подстановки считается перед началом шаблона. Такое умолчание не вызовет
    //NB обращения за пределы шаблона, и позволит не обрабатывать специально старт алгоритма
    int iLastParamPos = -1;

    //AP 1.Поиск очередной точки подстановки c предыдущей
    while((iParamPos = strTemplate.find("%", iLastParamPos+1)) != string::npos)
    {
        //AP 1.1.Копирование в результат содержимого шаблона с прошлой точки до найденой
        strRet.append(strTemplate.substr(iLastParamPos+1, iParamPos-iLastParamPos-1));
        //AP 1.2.Добавление в результат следующей подставляемой строки из вектора
        if(stvParams.size()>iParamIdx)
            strRet.append(stvParams[iParamIdx++]);
        iLastParamPos = iParamPos;
    }
    //AP 2.Копирование в результат остатков шаблона, не содержащих точек подстановки
    strRet.append(strTemplate.substr(iLastParamPos+1, strTemplate.size()-iLastParamPos-1));
    //AP 3.Стирание из строки символов подстановки, если необходимо
    if(removeFormatSymbs)
    {
        int fsPos;
        while((fsPos = strRet.find("%")) != strRet.npos)
            strRet.erase(fsPos, 1);
    }

    //OP Возврат результата
    return strRet;
}

OZ> //IP Заполнение шаблона строками из вектора(точки подстановки %)

Я боюсь получит кучу минусов и фиии... Но для меня IP,NB,AP,OP — нетривиальные индитификаторы, которые нужно запоминать как аббревиатуру английских букв, и постоянно менять регистр при документировании кода (дополнительные 2 нажатия сочитания клавиш переключения регистра). Почему не использовать символьные обозначения? Типа IP заменить на =, NB на *, AP на + и OP на ! ??? Читабельности не уберет и не прибавит, но скорость документирования возрастет....

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

Здравствуйте, MP321, Вы писали:

MP> Например комментарий "//OP Возврат результата" ну совершенно не нужен.
Угу, а если он кому-то нужен (отследить множественные точки выхода) — его можно сгенерировать автоматическими средствами.

Здравствуйте, OriginalZealot, Вы писали:

OZ>Вобщем часто вижу комментарии типа: "здесь пишем в файл", "считаем чего-нибудь"
OZ>В качестве комментария к функции запись типа: "рисует дугу на битмапе"
OZ>Такой разброд мне совсем не нравится, особенно потом при попытке понять что это за код.
В свое время, долго на работе спорила с коллегами и наконец-то поняла их правоту.
В теле функций коментариев быть на должно !!!!
Они могут/должны быть
1. в начале каждого файла
2. перед оперделением класса
3. перед определением членов класса/деклараций функций и т.д.
В общем то, что потом скармливается в DoxyGen
Если у вас возникла необходимость что-то коментарить внутри функции, занчит либо с дезайном косяк, либо имена даете кривые и т.д.

Помедоры не кидать !

Здравствуйте, ArhAngelVezel, Вы писали:

OZ>> //IP Заполнение шаблона строками из вектора(точки подстановки %)

AAV>Я боюсь получит кучу минусов и фиии... Но для меня IP,NB,AP,OP — нетривиальные индитификаторы, которые нужно запоминать как аббревиатуру английских букв, и постоянно менять регистр при документировании кода (дополнительные 2 нажатия сочитания клавиш переключения регистра). Почему не использовать символьные обозначения? Типа IP заменить на =, NB на *, AP на + и OP на ! ??? Читабельности не уберет и не прибавит, но скорость документирования возрастет....

Мне кажется тут стоит привлечь средства автоматизации — написать Add-in к сутдии, кторорый будте такие моменты отрабатывать горячими клавишами.

Здравствуйте, A.A.L., Вы писали:

AAL>В теле функций коментариев быть на должно !!!!
AAL>Если у вас возникла необходимость что-то коментарить внутри функции, занчит либо с дезайном косяк, либо имена даете кривые и т.д.

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

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

Здравствуйте, MP321, Вы писали:

MP>На мой взгляд:
MP>во-первых слишком много комментариев — они загромождают код, и уменьшают его читабельность и
MP>во-вторых они должны быть ориентированны на решаемую проблему, а не на то, каким образом что-то делает код в конкретном месте. Например комментарий "//OP Возврат результата" ну совершенно не нужен.

Лично я, настраиваю комметарии таким образом в редакторе, чтоб они были для меня "не видны", т.е. обычно это серый цвет. Это позволяет их как бы "фильтровать" зрением.

Главное то, что код и комментарии отвечают на разные вопросы — Код -> Как? а комментарии -> Что? Абсолютно самодокументируемого кода не существует. Например в коде могут присутствовать неявные условия на принимаемые на вход данные, особенности работы, которые приемлемы для данной программы и т.п.

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

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

Здравствуйте, A.A.L., Вы писали:

AAL>В теле функций коментариев быть на должно !!!!

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

Здравствуйте, OriginalZealot, Вы писали:

OZ>Здравствуйте, A.A.L., Вы писали:

AAL>>В теле функций коментариев быть на должно !!!!
AAL>>Если у вас возникла необходимость что-то коментарить внутри функции, занчит либо с дезайном косяк, либо имена даете кривые и т.д.

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

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

1. В твоем случае название Format — слишком общее
2. Тупой цикл for (size_t i...) if (template_[i] == '%') — выглядел бы куда понятнее, а работал бы нисколько не медленнее.

Здравствуйте, MP321, Вы писали:

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

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

MP>во-вторых они должны быть ориентированны на решаемую проблему, а не на то, каким образом что-то делает код в конкретном месте. Например комментарий "//OP Возврат результата" ну совершенно не нужен.

Кроме того, такие комментарии структурируют код — существенно проще и понятнее писать метод/функцию предварительно написав такие комментарии.

Комментарий "//OP Возврат результата" мне и самому не нравится, но если точки выхода то помечать нормально, то не помечать — некоторые будут выпадать из внимания при чтении кода. Тут бродит мысль о том, что бы для коротких или особо ясных методов использовать радикально другой стиль комментирования — т.е. ни единого комментария внутри метода. Но мне кажется это стоит как-то особо пометить, каким-то хорошо видимым символом в комментарии перед функцией. Например вот так:

// *** Заполнить шаблон строками из вектора(точки подстановки %) ***
string Format(string strTemplate, vector<string> stvParams, bool removeFormatSymbs)
{
    тут код с подробными комментариями по ранее описанной системе
}

// Проверить режим работы чего-нибудь
int CheckWorkMode()
{
    тут код вообще без комментариев, но хорошо структурированный, сдизайненый и с понятными названиями
}

Здравствуйте, Gadsky, Вы писали:

G>Здравствуйте, OriginalZealot, Вы писали:

G>1. В твоем случае название Format — слишком общее
G>2. Тупой цикл for (size_t i...) if (template_[i] == '%') — выглядел бы куда понятнее, а работал бы нисколько не медленнее.

3. И, кстати, строки и вектора надо передавать как константные ссылки.

Здравствуйте, A.A.L., Вы писали:

AAL>В общем то, что потом скармливается в DoxyGen
AAL>Если у вас возникла необходимость что-то коментарить внутри функции, занчит либо с дезайном косяк, либо имена даете кривые и т.д.

В данном случае комментарии становятся дополнительной частью контракта. Т.е. описывают некоторые особенности и возможности. НО отсутствие комментариев в коде нужно не для его чтения в своюбодное время (кто будет читать код, который работает, а следовательно, когда код работает никому мешать они не будут), а во время исправления ваших ошибок, а вот здесь они будут очень важны. Не стоит напоминать, что качество комментариев, т.е. когда они к месту вырабатывается с опытом, просто не надо боятся править комментарии. Если не хватает — добавте, считаете лишними — уберите. Суть качественных комментариев — повысит читабельность при дебаге и поиске ошибок.

Плюс, в языках, на которых некоторые алгоритмы реализуются не очень естественно — желательно чтоб был комментарий, описывающий алгоритм в оригинальном виде, ведь для реализации алгоритма могут быть применены оптимизации, что затруднит его чтение. Например в С быстрая сортировка (если не видеть названия) выглядит не так естественно как на Хаскелл.

Здравствуйте, MP321, Вы писали:

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

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

MP>во-вторых они должны быть ориентированны на решаемую проблему, а не на то, каким образом что-то делает код в конкретном месте.

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

Здравствуйте, OriginalZealot, Вы писали:

OZ>Я в процессе работы разработал такой вот стандарт комментирования:
[...skip...]
OZ>Один комментарий внутри метода, описывающий логику работы метода как длительное действие — "Рисование дуги на битмапе" (так называемая точка входа).
[...skip...]
OZ>Отдельный комментарий на каждую точку возврата из функции/метода в форме описания длительного действия результативного завершения виполнения функции/метода — "Успешное завершение, возврат идентификатора" (так называемая точка выхода).

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

Здравствуйте, OriginalZealot, Вы писали:

OZ>

OZ>// Заполнить шаблон строками из вектора(точки подстановки %)
OZ>string Format(string strTemplate, vector<string> stvParams, bool removeFormatSymbs)
OZ>

Я конечно извиняюсь, что не по теме, но зачем передавать строки и массивы строк по значению ?
Как правило их передают по константной ссылке.

Здравствуйте, OriginalZealot, Вы писали:

OZ>Я в процессе работы разработал такой вот стандарт комментирования:

А по-моему, слишком сложно. У тебя комментарии идут как отдельный код вокруг основного кода. Тут вошли, тут вышли, н езабыть согласовать.

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

Идеально конечно — когда код понятен без комментариев. Т.е. для метода — нрмальное описание с тем, что в нее приходит, и что с этим делается. В некоторых случаях — туда же можно вписать общий алгоритм и примеры использования. А в коде — писатьп онятнее и только неочевидные места — комментировать.
Писать же комментарий к каждой строчке,в ключая return result; — ну это бессмысленно и вредно (загромождение кода).

Отслеживать связи между комментариями (вход-действие-выход) — это уже совсем черезмерно. Можно дойти до комментариев к комментариям (NB, IP, OP уже зародыши таких метакомментариев). А вроде вдеь комментраии служат для упрощения понимания кода, а не для галочки "код сильно откомментирован".

Здравствуйте, A.A.L., Вы писали:

AAL>В теле функций коментариев быть на должно !!!!
AAL>Они могут/должны быть
AAL>1. в начале каждого файла
AAL>2. перед оперделением класса
AAL>3. перед определением членов класса/деклараций функций и т.д.
AAL>В общем то, что потом скармливается в DoxyGen
AAL>Если у вас возникла необходимость что-то коментарить внутри функции, занчит либо с дезайном косяк, либо имена даете кривые и т.д.

AAL>Помедоры не кидать !

Кину!

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

Здравствуйте, OriginalZealot, Вы писали:

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

Моё мнение:
1. Если пишешь комментарий, надо сначала подумать, нельзя ли его выразить сердствани языка
2. bool removeFormatSymbs -- антипаттерн "Швейцарский армейский нож". Наверное, стоит выделить в отдельную функцию
3. Венгерская нотация мастдай

Я бы сделал что-то типа:

// Заполнить шаблон строками из вектора (точки подстановки %)
string format(string template, vector<string> params)
{
    string ret;
    int patamIdx = 0;
    int paramPos = 0;
    int lastParamPos = -1;

    while(findNextPlaceholder(...))
            processPlaceholder(...)
        appendRestOfTemplate(...);
    
        return ret;
}
string removeFormatSymbols(string s)
{
 ...
}