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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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