Flash - статьи

Комментирование кода


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

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

Вот пример простого комментария для переменной:

var clicks = 0; // переменная для подсчета нажатий кнопки

Блочные комментарии полезны для больших кусков текста:

/*

Инициализирует переменную clicks, хранящую количество нажатий кнопки.

*/

Ниже приведены некоторые общие методы для указания особо важных комментариев (в скобках предложены русскоязычные аналоги):

// :TODO: topic (// :СДЕЛАТЬ: тема)

Указывает, что код нужно доделать или сделать что-то еще.

// :BUG: [bugid] topic (// :ОШИБКА: [номер ошибки] тема)

Показывает известную ошибку ("глюк", "баг"). Комментарий также должен объяснять, в чем состоит проблема, и содержать "bug ID" (номер "бага"), если необходимо.

// :KLUDGE: (// :ВОЗМОЖЕН ДРУГОЙ ВАРИАНТ:)

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

// :TRICKY: (// :РИСКОВАНО:)

Уведомляет разработчиков, что код со многим взаимосвязан (его изменение повлечет изменения в других местах). Это совет разработчику: "подумай, прежде чем что-то изменять".

Пример

/*

:TODO: msw 654321: проблемы с отображением больших объемов данных из БД. Наверное, следует разбивать данные на более мелкие порции для каждого запроса.

*/



Содержание раздела