Стандарты оформления кода PHP
Prev		Next

Стандарты оформления кода PHP

Глава 20. Формат описания gotchas

Ключевое слово gotcha должно ставиться в самом начале комментария.

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

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

Пример

// :TODO: tmh 960810: возможны проблемы со скоростью работы
// Нам точно понадобится хэш-таблица, но пока
// мы используем линейный поиск.

// :KLUDGE: tmh 960810: потенциально небезопасное приведение типа
// Приведение понадобилось для восстановления производного типа. Возможно
// здесь понадобится виртуальный метод или шаблон.

См. также: Документация интерфейсов и реализаций.

Prev	Home	Next
Несколько комментариев по комментариям	Up	Зарезервированные слова для описания gotchas