Учебник по программированию/Как хорошо комментировать?

Это пособие для начинающих. Просьба вносить предложения на странице обсуждения. Автор глобального проекта "Учебник по программированию" Волобуев Илья Евгеньевич.

Это часть проекта "Учебник по программированию" предназначена для тех, кто читал уже тему комментарии в проекте TGP. Посмотреть другие учебники этого автора

Советы и ошибки в оформлении комментариев.

Комментарии в программах

Начнем. У многих я думаю возникал вопрос: "Как хорошо и понятно для себя и для других комментировать?". Тут мы и поговорим. Дадим ответ на этот вопрос. Прежде всего начнем с неудачных комментариев в коде сайта. Вот ошибка пользователя:

<!--Сайт имеет синий фон. Две формы для авторизации пользователей. Три картинки.-->
код сайта

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

Добавлять комментарии правильнее в конце каждой строки. То есть так:

код сайта <!--комментарий-->

Хотя так делать правильно, но есть и нюансы по добавлению комментариев в конец строк.

Нюансы комментирования

Добавлять комментарии в конец каждой строки - это удобно, но нужно знать некоторые правила по комментированию. Например не надо употреблять много научных терминов по информатике. Эти комментарии тогда просто не принесут пользы новичкам, а тем более Вам. Потому, что они не поймут и в конце концов все кончится бесконечными вопросами. Во-вторых не надо писать например на русском языке комментарии, если Вы находитесь в Англии. Это неуместно лишь по одной причине: "Никто Вас не поймет (почти никто)."

Два типа комментариев

Однострочные

Рассмотрим типы комментариев и начнем с первого - однострочные комментарии. Однострочные комментарии - это комментарии, которые располагаются после какого-то символа или совокупности символов и продолжающихся до конца строки. Мы уже встречались с таким типом комментариев. Когда читали параграф VBA / Комментарий.

Зачем же нужны однострочные комментарии? В основном такие комментарии используются в том случае, если требуется описать что-либо очень кратко. Это значит, что не надо писать такие комментарии, которые чтобы прочитать требовалось использовать полосу прокрутки. Например, вот тут пользователь не поленился и подробно описал код программы:

// создадим наши любимы переменные, со значениями (не очень большими) 23883 и 73773
var a = 23883;
var a = 73773;

И тут мы встретили сразу одну ошибку. Не показалось ли вам, что программист слишком много вставил юмора в комментарии как будто это был не комментарий, а часть книги "Юмор у программистов"? Это выглядит смешно для обычного пользователя и не смешно для программиста, которому для просмотра всего комментария пришлось использовать полосу прокрутки. Я думаю вам понятны ошибки других людей и вы не будете повторять их. Как говориться: "Учусь на чужих ошибках".

Многострочные

Сравнение двух типов комментариев.