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

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

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


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


class MyClass{


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


//////
}


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