Басни на ночь — Хорошие имена как залог успеха

Тогда вопрос.

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

Check GetCheck(int empId){
    ....
    var taxes=GetTaxes(empId, paymentType); // эта функция генерит свои ошибки
    var fines=GetFines(empId); // эта тоже

    return Calculate(taxes, fines, period) //и эта
}

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

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

Для Api безусловно нужны комментарии, а так, я не считаю, что они являются обязательным фактором.

P.S. всё вышесказанное является ИМХО и не хочу сказать что сказанное является абс. истинной. Кто то без комментов жить не может, а кто то легко обходится.

Басни на ночь — Хорошие имена как залог успеха

и еще вот к примеру. Есть класс с функциями. У функций есть комменты. Решили сделать рефакторинг дабы привести в порядок содержимое самих функций. В итоге некоторые функции разбились на несколько новых, пара функций была смержена, и т.д.
В случае цели писать комменты, придется для всех модифицированных функций проверять соответствие комментария с назначением функций. А если вы упустили одну из функций из вида, тогда комментарий будет вводить в заблуждение. После пары таких случаев программист начнет сомневаться в комментах. Дабл чекинг выходит.

Басни на ночь — Хорошие имена как залог успеха

Хорошее имя функции сделает тоже самое. Понимаю что не всегда это достижимо, но как правило более чем возможно.

Басни на ночь — Хорошие имена как залог успеха

Если у вас это регламент такой — то понятно. Но смысла особого не вижу в этом. Сочувствую вам если честно. Меня бы надолго не хватило.

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

Басни на ночь — Хорошие имена как залог успеха

понятно, что не все. Это не должно становится самоцелью. Но плодить коммента как документацию — увольте.
К вам вопрос — много комментво пишите? не надоедает? Я лично устаю быстро их писать.

/// ///Находится в состоянии загрузки
///
private bool isLoading;

/// /// Применить изменения
///

В таком
private void ApplyChanges(){
…
}

Не является ли это самоцелью?

Басни на ночь — Хорошие имена как залог успеха

P.S. спасибо за указание ошибки. поправил статью

Басни на ночь — Хорошие имена как залог успеха

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

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

P.S. между кодом с комментами и чистым кодом без комментов я выберу второе. Код может быть обновлен, а комменты будут за ленью/или по др. причине забыты. В итоге комменты оторваны от кода. А это зло.

Басни на ночь — Хорошие имена как залог успеха

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

Басни на ночь — Хорошие имена как залог успеха

Спасибо, возьму на заметку

Басни на ночь — Хорошие имена как залог успеха

P.S. при написании не использовал книгу как источник. Написал основные принципы хорошего стиля.

Басни на ночь — Хорошие имена как залог успеха

А у меня очень хорошая память, Так что двойку прошу не ставить ;)
Новичкам будет полезно.
А то что чуть ли не дословно — мхм, можно было на древнерусском языке, но смысл. Ниже приведены слова из книги Питера Гудлифа. Книги хоть и разные, контент очень похож.