?

Log in

No account? Create an account
November 2016   01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
cartoon

Миф о документации, продолжение

Posted on 2011.06.18 at 23:06

Comments:


Gaperton
gaperton at 2011-06-19 20:01 (UTC) (Link)
> И вот что в этом блоке делается -- ну ни разу не понятно, хотя сам год назад это писал. Я это к чему: иногда случается, что не угадаешь с комментариями.

Комментарии тут не причем. Код надо лучше писать. Хорошему коду комментарии не нужны.

Если ты в принципе можешь нормально описать принцип в доке, то ты в состоянии это сделать в комментариях. Если ты можешь это сделать в комментариях - то ты можешь по человечески структурировать код, и дать переменным и функциям осмысленные имена, чтобы уменьшить количество комментариев.

Нет никакого смысла писать путанно, заставляя людей много читать. Если для понимания кода нужна специальная дока - к чертям такой код.
hedgeov
hedgeov at 2011-06-19 20:25 (UTC) (Link)
Там ровно 5 строк, 2 условия и 3 присвоения. Все переменные совершенно понятные, но вот зачем они делают то, что делают -- на момент написания было очевидно, а на момент прочтения уже не очень -- пришлось потратить время. Просто при этом всё вокруг очень доходчиво и понятно, и с комментариями, и с говорящими именами -- я всегда для себя код пишу, ибо память ну оочень девичья :)
Пойнт в том, что на выразительные средства языка надейся, а сам -- не плошай. Лишний коментарий еще никогда не вредил, а экономия на "дисковом пространстве" (да, была и такая отговорка) всегда выходит себе дороже. При этом комментарий должен описывать "зачем это делается", а не совершенно очевидное из кода "присвоим переменной зю значение 3.1415926".
Previous Entry  Next Entry