Исправление Nervous, (текущая версия) :
Комментарии должны отвечать на вопрос «зачем?», а код должен быть написать так, чтобы код отвечал на вопрос «как?».
В целом согласен. Правда, не всегда в документации метода можно описать, зачем он делает то, что делает — его роль в общей картине не обязательно ему известна, это скорее забота и ответственность кода, который его вызывает. А вот что он делает (что возвращает) — уже целиком его ответственность.
Исходная версия Nervous, :
Комментарии должны отвечать на вопрос «зачем?», а код должен быть написать так, чтобы код отвечал на вопрос «как?».
В целом согласен. Правда, не всегда в документации метода можно описать, зачем он делает то, что делает — его роль в общей картине не обязательно ему известна. А вот что он делает (что возвращает) — уже целиком его ответственность.