Ясно, что речь идет о комментариях? Если нет, то не лучше ли было бы, чтобы заголовок был «Комментарии: Не подскажите как, скажите почему!»?
Это проблема, которую мы видим повсюду. Есть комментарии, которые без всякого контекста ничего не значат. В других вам нужно будет прочитать весь код (или статью), чтобы понять смысл, и даже тогда он может вводить в заблуждение или просто устареть.
Вероятно, это применимо к большинству случаев, но вам действительно нужен четкий, чистый код, который каждый может прочитать и понять, что происходит.
Это если вам действительно не нужен какой-то менее читаемый, более сложный код по какой-либо причине (обычно из-за производительности). В таком случае, пожалуйста, прокомментируйте, что и как происходит. Но также сделать…
Комментарий ПОЧЕМУ!
Почему вы используете менее читаемый код?
Почему бы мне не изменить порядок чего-либо?
Почему это здесь?
Почему это было использовано вместо XYZ?
В зависимости от того, что вы делаете, вашего уровня и уровня ваших коллег, что-то обычное для одного может быть ракетостроением для другого. Это не то, о чем идет речь.
Если вам придется вернуться к коду в следующем месяце, вы должны знать, что делает код, прочитав его. Вопрос в другом: зачем это здесь?
Некоторые фрагменты могут говорить сами за себя, например transformXtoY, но почему и где мне это делать?
Я также не говорю везде ставить «почему», но если вы пересматриваете код и тратите время на выяснение чего-то, или если даже после рефакторинга кто-то всегда что-то путает… тогда да, добавьте «почему».
Мало того, запросы на слияние — отличный источник, чтобы найти некоторые из тех мест, которые нуждаются в комментариях «почему».
На PR кто-то спросил, почему ты что-то сделал?
Только не говори им! Мало того, не делайте этого вне PR и заканчивайте. Рефакторинг кода, добавление комментария о том, почему он здесь, и тогда каждый раз, когда кто-то пересматривает этот фрагмент кода, он будет там, почему.
