Хорошие случаи использования комментариев

Question

Я всегда ненавидел комментарии, которые заполняют половину экрана звездочками, просто чтобы сказать вам, что функция возвращает строку, я никогда не читал эти комментарии.

Однако я читаю комментарии, которые описывают, почему что-то делается и как это делается (обычно однострочные комментарии в коде); они очень полезны при попытке понять чужой код.

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

Примером может быть:

//loop though all the names from n to j - 1

Кроме этого, я не могу себе представить, почему кто-то будет тратить драгоценное время на написание комментариев, когда он может писать код.

Я прав или нет? Я что-то пропустил? О каких других хороших случаях использования комментариев я не знаю?

Answer 1

Я всегда ненавидел комментарии, которые заполняют половину экрана звездочками, просто чтобы сказать вам, что функция возвращает строку, я никогда не читал эти комментарии.

Некоторые комментарии в том же духе, обычно не с форматированием , которое extreme, действительно существуют, чтобы помочь таким инструментам, как JavaDoc и Doxygen, генерировать документацию для вашего кода. Это, я думаю, хорошая форма комментария, поскольку он имеет как машиночитаемый, так и машиночитаемый формат для документации (так что машина может переводить его в другие, более полезные форматы, такие как HTML), приближает документацию к коду что он документирует (так что если код изменяется, документация, скорее всего, будет обновлена, чтобы отразить эти изменения), и, как правило, дает хорошее (и немедленное) объяснение кому-то новичку в большой базе кода, почему существует конкретная функция. 1007 *

В противном случае, я согласен со всем остальным, что было сказано. Комментируйте почему, и комментируйте только тогда, когда это не очевидно. Помимо комментариев Doxygen, мой код обычно имеет очень мало комментариев.