Стандарт за писане на код в PHP

PHP » PHP

thelordofweb   трудност:    видян: 38823

Реализация и интерфейс на документацията

Има две главни аудиенции за документация :

• За обикновени потребители
• За разработчици

С малко предвидливост ние можем да извлечем двата вида на документацията пряко от кода на източника.

За потребители

Потребителите на класата имат нужда от информация за класа и неговия интерфейс. Когато е структурирана правилно може да бъде извлечена пряко от файла. При запълване на заглавната част, коментирайте блоковете за клас, като само включете информация, нужна за програмиста, които използват класът. Не копайте в детайли за реализация на алгоритъм освен ако детайлите са нужни за потребител на класа. Обмислете коментари в заглавната част и ги напишете достатъчно лесно разбираеми за всеки човек.

За разработчици

Този начин на документиране изисква задълбочени познания за клас и неговото приложение. Този вид коментар се съдържа в сорс-файлът. Блокове за коментар на заглавната част в сорс-файл трябваше да покрият въпроси за алгоритмите и възможни други решенията при дизайна. Блокове за коментар в реализацията на метод трябваше да обясняват дори повече.

Документация на директория

Всяка директория трябваше да има файл README, който покрива :

• Предназначението на директорията и това, което тя съдържа.
• Един ред коментар за всеки файл. Може да бъде извлечен от заглавната част на файла.
• Описва пътя на изграждане и инсталиране.
• Насочете хората към взаимно-свързани ресурси :

o <!--[endif]-->Директории с код

o <!--[endif]-->Онлайн документация

o <!--[endif]-->Документация на хартия

o <!--[endif]-->Документация за дизайн

• Каквото и да е, което може да помогне на някой.

Помислете си, че нов човек започва работа върху 6 месечен писан от вас код. Изследователят е сам и уплашен. Той трябва да бъде способен да илюстрира целият проект прекосявайки дървото от директории и четейки файловете README, MAKEFILES и заглавните части на кода. Това може и да сте вие!