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

В качестве примера: TeX: The Program и Metafont: The Program.

>Как правильно комментировать код?

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

Chapter 7: Commenting

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

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

> также и такие места, которые сам чувствуешь

+1

Хоть и дрожат руки от покушения на святое 8), приступим:

> 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, это именно комментарий).

> HOW - тоже важно.

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

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

>> HOW - тоже важно.

>Линус прав.

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

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

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

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

Ну так блин, если у тебя есть фрагмент кода, в который без димедрола и не въедешь, его следует а) переписать и упростить; б) спрятать в отдельную функцию с понятным именем и подробным комментарием.

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

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

Я думаю здесь имеется ввиду несколько другое,
WHAT это как раз про алгоритм,
а HOW это коменты типа

++i;//а здесь мы увеличиваем i на единицу

> фрагмент кода, в который без димедрола и не въедешь, его следует а) переписать и упростить; б) спрятать в отдельную функцию с понятным именем и подробным комментарием.

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

> i+i;//а здесь мы увеличиваем i на единицу

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

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

и?

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

>и?

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

> i+i;//а здесь мы увеличиваем i на единицу

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

Это я неправильно процитировал :/

просто забавно и в тему получилось, не принимай на свой счёт! :)

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

ну да, я привел этот пример в качетсве ненужного коментария,
зачем это было повторять?

> ну да, я привел этот пример в качетсве ненужного коментария

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

Комментарии в программе подобны подстрочнику в иноязычной книге. Они помогают студентам, но совершенно сбивают с толку человека знающего, так как говорят то же самое другими словами. В любом случае, хорошая книга всегда пишется на одном языке.

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

> Они помогают студентам, но совершенно сбивают с толку человека знающего, так как говорят то же самое другими словами.

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