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

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

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

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

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

Отдельный комментарий на каждое нестандартное, логически непрозрачное место в коде (пометка 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;
}