Комментирование кода

как для себя родного

Comments are good, but there is also a danger of over-commenting. NEVER try to explain HOW your code works in a comment: it's much better to write the code so that the _working_ is obvious, and it's a waste of time to explain badly written code.

Generally, you want your comments to tell WHAT your code does, not HOW. Also, try to avoid putting comments inside a function body: if the function is so complex that you need to separately comment parts of it, you should probably go back to chapter 5 for a while. You can make small comments to note or warn about something particularly clever (or ugly), but try to avoid excess. Instead, put the comments at the head of the function, telling people what it does, and possibly WHY it does it.

(c) /usr/src/linux/Documentation/CodingStyle

> Generally, you want your comments to tell WHAT your code does, not HOW.

HOW - тоже важно. Другое дело, что можно просто сослаться на алгоритм в литературе.

> Also, try to avoid putting comments inside a function body

Но бывают сложные места в коде, где комментарий просто необходим.

Вообще, кроме комментариев к компонентам программы, очень полезны комментарии более высокого уровня, так сказать, "вид с птичьего полета" (это _не_ design document, это именно комментарий).

Линус прав. Тут всё дело в особенностях человеческого мышления: для того, чтоб понять, как работает кусок кода, надо целиком держать его в голове. Если функция большая, её приходится как-то мысленно делить на мелкие куски. И комментарии в теле функции в основном помогают выделить эти самые более мелкие куски, и врубиться, что делает каждый кусок в отдельности. Поэтому разумно все эти куски сделать отдельными функциями, и в комментариях написать, ЧТО делает каждая из них. И продолжать процесс разбиения до тех пор, пока все функции не станут достаточно простыми для понимания.

А те, кто не согласны с Линусом, и считают, что большие функции с построчными каментами это ваще круто, могут сравнить код ядра линукса и ядра БСД. :)

>Линус прав.

Почитай Documentation/ManagementStyle ;)

В данном случа он не прав - небольшой комментарий может 1) сохранить много времени, потраченного на понимание фрагмента кода 2) спасти от его неправильного понимания.

> считают, что большие функции с построчными каментами это ваще круто

Где ты видел таких? В этом треде они пока не проявились.

А вот функции, состоящие из сплошных житрожопых вывертов и комментариев к ним, встречались мне, в основном, в старых программах на фортране. :) И как офигенно прекрасно, что эта практика постепенно уходит в прошлое!

или c) прокомментировать ;)

Ну, это очевидно бесполезный комментарий

>и?

<shrug> и таких комментариев писать не надо.

i+i? :-) Это даже вредный комментарий. Дезинформация.

В качестве еще одного примера ненужного комментария :-P

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

Во! В самую точку!