понедельник, 18 января 2010 г.

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

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

И предложение:
Мне кажется нужно внедрить такую практику как документирование кода, причем не «глупые» проставления комментариев «// i - iterator», а полноценное описание классов, методов, функций и их входных/выходных параметров. Документация кода – это та часть проекта, которую мы обычно опускаем: сроки поджимают, ТЗ снова изменилось, а там еще что-то даже и не начинали делать, или мнение – что хороший код не нуждается в документации.


Пример:
/**
* Описание класса: общая информация, параметры, способы вызова или создания объекта, итп
*/


class MyClass{


/**
* An error message.
* @var string
*/
$error = "";


//////
}


Документировать абсолютно весь код - это глупо. Документировать предлагаю классы, методы и свойства framework, базовых модулей и "хитрых" частей наших проектов. В дальнейшем это поможет более быстро и осмысленно разбираться в структуре framework и модулей. Так же такое документирование позволяет генерировать документацию по коду на лету и показывать справочную информацию в системах разработки (Eclipse, phpDesigner и пр)

2 комментария:

  1. Гы, актуально для тех что сидит в Far и Блокнотах, ну в общем в тех редакторах, где понятия проект.

    ОтветитьУдалить
  2. Раз уж затронули тему стандартов, то предлагаю так же ввести и использовать единые стандарты кодирования. Ниже представлен список основных стандартов.

    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

    ОтветитьУдалить