И предложение:
Мне кажется нужно внедрить такую практику как документирование кода, причем не «глупые» проставления комментариев «// i - iterator», а полноценное описание классов, методов, функций и их входных/выходных параметров. Документация кода – это та часть проекта, которую мы обычно опускаем: сроки поджимают, ТЗ снова изменилось, а там еще что-то даже и не начинали делать, или мнение – что хороший код не нуждается в документации.
Пример:
/**
* Описание класса: общая информация, параметры, способы вызова или создания объекта, итп
*/
class MyClass{
/**
* An error message.
* @var string
*/
$error = "";
//////
}
Документировать абсолютно весь код - это глупо. Документировать предлагаю классы, методы и свойства framework, базовых модулей и "хитрых" частей наших проектов. В дальнейшем это поможет более быстро и осмысленно разбираться в структуре framework и модулей. Так же такое документирование позволяет генерировать документацию по коду на лету и показывать справочную информацию в системах разработки (Eclipse, phpDesigner и пр)
понедельник, 18 января 2010 г.
Документирование кода
M. Gura прислал свое видение по организации работы и, что важно, отметил необходимость документации.
Подписаться на:
Комментарии к сообщению (Atom)
Гы, актуально для тех что сидит в Far и Блокнотах, ну в общем в тех редакторах, где понятия проект.
ОтветитьУдалитьРаз уж затронули тему стандартов, то предлагаю так же ввести и использовать единые стандарты кодирования. Ниже представлен список основных стандартов.
ОтветитьУдалить1. PEAR Coding Standards (http://pear.php.net/manual/en/standards.php)
2. Zend Framework Coding Standard (http://framework.zend.com/manual/en/coding-standard.html)
3. Symfony Coding Standards (http://trac.symfony-project.org/wiki/HowToContributeToSymfony#CodingStandards)
4. Cake PHP Coding Standards (http://trac.cakephp.org/wiki/Developement/CodingStandards)
5. DB Medialab PHP Coding Standard (http://www.dagbladet.no/development/phpcodingstandard/)
6. Стандарты оформления кода PHP (http://tony2001.phpclub.net/doc/standard/
7. PHP Coding Guidelines (http://www.evolt.org/article/PHP_coding_guidelines/18/60247/
8. GForge: PHP Coding Standards (http://gforge.org/docman/view.php/1/2/coding-standards.html