Заметил, что чем хуже написан код, тем больше в нём пояснительных записок. В следствие чего я поставил себе цель писать код так хорошо, насколько это вообще возможно с рациональной точки зрения.
Я не пишу описание функции, какие переменные заглатывает, какие сущности выкидывает, объект это, или контроллер. Всё это понятно из названий самих объектов.
Мне сейчас достаточно написать просто todo что этот код отстой и я в скором времени его сделаю лучше, нежели просто написать комментарий "вот эта функция делает то, мне было плохо с воскресенья на понедельник, пожалейте меня". Соответственно по ощущениям объем бессмысленной работы сократился, ведь теперь не нужно пролистывать в каждой функции строк 15 тупо комментариев, что эта функция принимает, что возвращает и т.д. Я просто смотрю в код и всё.
Нужно различать технические комментарии, которые по сути являются надстройкой над языком, и пояснения к коду.
В вопросе все свалено в кучу, и ответ от тов. куратора получился таким же. В итоге все говорят о разном и никогда не придут к единому мнению (причина 99% споров в интернете).
Я так понимаю, о технических комментариях АКА phpdoc (о которых говорит тов. куратор) речь сейчас не идет. Если идет, то автор приглашается объяснить, чем они его не устраивают.
Если же автор говорит о пояснениях к коду, то позиция совершенно правильная, такой подход называется самодокументируемый код, впервые упомянутый великим Фредериком Бруксом еще в 60-х годах прошлого века.
Да, коменты в стиле phpdoc я отказался писать ибо это просто бессмысленная работа если есть соглашение о наименовании и стилистики кода. Скорее вопрос вопрос к комментам типа "объяснить" что эта строчка делает, но обычно я пишу для этого тупой код, ибо код write-only меня бесит.
Вот здесь https://learn.javascript.ru/comments очень хорошо пояснено про комментарии. Там пояснено на примере javascript, но актуально для всех языков.
Ну мне кажется сложная логика может быть только для инфраструктурного кода на котором базируются более мелкие подпрограммы. Обычно для такого кода комменты обязательны и лучше даже с примерами, а вот написать три непонятных условия с присвоением к одной и той же переменной разного значения это уже плохой код. Тут даже мне кажется комментарии не помогут, ибо код может быть багованным, а такое бывали и не раз.
Средний
