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

PHP » PHP

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

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

Коментари

Коментарите трябваше да разкажат история

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

Кога да документираме?

Коментарите трябваше да документират решения. Използвайте коментари във всеки възможен момент, чрез което ще опишете стореното от вас и ще знаете какво сте правили и защо.

Използвайте заглавия

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

Подредба на коментарите

Всяка част на проектът има специфична подредба за коментар.

Правете описанието разбираемо

Вградените ключови думи се използуват да описват потенциални въпроси и проблеми. Знайте, че робот ще анализира синтактично вашите коментари търсейки ключови думи и ще ги пренебрегне след изтеглената информация, представяйки я така че да е ясна за хората без голямо опит.

Ключови думи

:TODO: тема

С това отбелязваме неща, които не бива да забравяме или пропуснем

:BUG: [bugid] тема

Ако знаем за някой бъг, тука обясняваме за него и пожелание може да предоставим идентификационния номера на бъга.

:KLUDGE:

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

:TRICKY:

Казвате, че следващият код е много измамен така че да не се отиват да го променят без сериозно обмисляне.

:WARNING:

Пазете се от нещо.

:PARSER:

Понякога вие трябва да работите върху проблем, който анализирате в момента. Документирайте го. Проблемът може да бъде подминат в края на краищата.

:ATTRIBUTE: стойност

Общата форма за атрибут вградена в коментар. Вие можете да опишете вашите атрибути и те ще бъдат извлечени.

• Ключовата дума трябва да е първа в коментара
• Коментарите могат да се състоят от много редове, но първия ред трябва да съдържа същността - съдържание, смислено резюме.
• Името на автора и датата на забележката трябваше да бъдат част от коментарът. Така може да разберем кога и от кой е прибавен. Вграждането на информация за дата позволява на друг програмист да си направи заключение. Добавянето на автора ни помага да разберем при нужда кой да попитаме.

Пример:

	   // :TODO: tmh 960810: possible performance problem

	   // We should really use a hash table here but for now we'll

	   // use a linear search.

	   // :KLUDGE: tmh 960810: possible unsafe type cast

	   // We need a cast here to recover the derived type. It should

	   // probably use a virtual method or template.