The OpenNET Project / Index page

[ новости /+++ | форум | wiki | теги | ]

Каталог документации / Раздел "PHP" / Оглавление документа

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

Существует два вида читателей для вашей документации:

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

Пользователи класса

Пользователям класса необходимы сведения об интерфейсе класса; такие сведения легко добываются из заголовков, если, конечно, они правильно структурированы. При заполнении заголовочного блока комментариев, давайте только сведения, необходимые для использования класса. Не вдавайтесь в подробности реализации алгоритма - не надрывайтесь. Исключение составляют случаи, когда знание алгоритма необходимо для корректного использования класса. Воспринимайте заголовочный блок комментариев как без пяти минут главу из технического руководства.

Разработчики класса

Разработчикам класса требуется глубокое знание реализации класса. Комментарии этого типа находятся в файлах с исходным кодом класса; забудьте на время про особенности интерфейса. Заголовочный блок комментариев в исходнике должен описать все особенности алгоритма и решения по проектированию класса. Блоки комментариев внутри методов реализации должны предоставить ещё более подробную информацию.




Спонсоры:
PostgresPro
Inferno Solutions
Hosting by Hoster.ru
Хостинг:

Закладки на сайте
Проследить за страницей
Created 1996-2022 by Maxim Chirkov
Добавить, Поддержать, Вебмастеру