Что помещать в комментарии?

Прежде чем станешь писать, научись порядочно мыслить!

Гораций

Лучше совсем без комментариев, чем плохие комментарии – они дезинформируют читателя и вводят его в заблуждение. Что же следует помещать в комментарии? Вот несколько основных советов, как повысить качество комментариев.

Описывайте «почему», а не «как»

Это ключевой момент, поэтому прочтите данный абзац дважды. Комментарии не должны описывать, как работает программа. Это видно из кода. В конце концов, исчерпывающим

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

Что помещать в комментарии?

Постоянно следите за тем, как писать: /* обновить структуру WidgetList из GlbWLRegistry */ или /* сохранить сведения о виджете на будущее */.

Комментируя одно и то же, во втором варианте вы излагаете смысл кода, а в первом просто описываете его действие.

При сопровождении фрагмента кода его задача меняется реже, чем способ ее решения, и поддерживать актуальность комментариев такого рода гораздо проще.Хорошие комментарии объясняют «почему», а не «как».В комментарии можно также объяснить, почему вы выбрали тот или иной способ реализации. Когда есть две стратегии реализации и вы предпочли одну из них, возможно, стоит объяснить в комментарии, на чем основано ваше решение.

Не нужно описывать код

Бесполезность описательных комментариев бывает очевидна: ++i; //увеличить i.

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

Один источник для каждого факта. Не копируйте код в комментариях.Не подменяйте код

Если вы видите комментарий, сообщающий чтото, что может быть выражено средствами самого языка (например, // доступ к этой переменной должен осуществляться только из класса foo), попытайтесь выразить это синтаксическим способом.

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

• Попробуйте разбить код на несколько функций, дав им хорошие имена, чтобы отразить логику программы.

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

• Если вы документируете условие, которое должно выполняться всегда, может быть, правильнее написать оператор контроля.

• Не следует преждевременно оптимизировать(и тем самым делать менее понятным) вой код.

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