Как видно из следующего фрагмента, HTML в комментариях к исходному коду выглядит отвратительно. Он затрудняет чтение комментариев именно там, где они должны легко читаться — в редакторе/IDE. Если комментарии должны извлекаться внешним инструментом (например, Javadoc) для отображения в веб-странице, то за украшение комментариев соответствующим кодом HTML должен отвечать этот инструмент, а не программист.
>/**
>* Задача для запуска тестов.
>* Задача запускает тесты fitnesse и публикует результаты.
>*
>*
>* Usage:
>* <taskdef name="execute-fitnesse-tests"
>* classname="fitnesse.ant.ExecuteFitnesseTestsTask"
>* classpathref="classpath" />
>* OR
>* <taskdef classpathref="classpath"
>* resource="tasks.properties" />
>*
>* <execute-fitnesse-tests
>* suitepage="FitNesse.SuiteAcceptanceTests"
>* fitnesseport="8082"
>* resultsdir="${results.dir}"
>* resultshtmlpage="fit-results.html"
>* classpathref="classpath" />
>*
>*/
Если вы должны написать комментарий, проследите за тем, чтобы он описывал находящийся поблизости код. Не излагайте информацию системного уровня в контексте локального комментария. Примером служит приведенный ниже комментарий Javadoc. Не считая того факта, что комментарий ужасающе избыточен, в него также включена информация о порте по умолчанию, притом что функция никоим образом не может управлять этим значением. И конечно, ничто не гарантирует, что комментарий будет изменен при изменении кода, в котором это значение определяется.
>/**
>* Порт, на котором будет работать fitnesse. По умолчанию 8082.
>*
>* @param fitnessePort
>*/
>public void setFitnessePort(int fitnessePort)
>{
> this.fitnessePort = fitnessePort;
>}
Не включайте в комментарии интересные исторические дискуссии или описания подробностей, не относящиеся к делу. Следующий комментарий был извлечен из модуля, который должен был проверять, что функция кодирует и декодирует данные в формате base64. Читателю кода совершенно не нужна заумная информация, содержащаяся в этом комментарии, — вполне достаточно номера RFC.
>/*
>RFC 2045 - Multipurpose Internet Mail Extensions (MIME)
>Часть 1: Формат тел сообщений
>раздел 6.8. Кодирование данных Base64
>В процессе кодирования 24-разрядные группы входных битов представляются
>в виде выходных строк из 4 закодированных символов. Слева направо 24-разрядная
>входная группа образуется посредством конкатенации 38-разрядных входных групп.