Универсальная вводная для крупных проектов
Есть сайт, помимо типового функционала коробки на него навёрнута интеграция с рядом сервисов, сделаны нестандартные вещи, обслуживающие специфический функционал, сайт сопровождается командой из 5+ разработчиков.
Какие проблемы могут быть
1. Трудности с подключением нового разработчика. Большой временной лаг на то, чтобы разобраться с уже реализованным функционалом.
2. Трудности с донесением изменений по архитектурной и функциональной части до других разработчиков.
3. Иногда могут возникать ошибки из-за использования устаревших функций написанных другим разработчиком, но при беглом взгляде другого вроде решающих его задачу итд.
4. Сложности при планировании новых функционалных блоков.
Проблема комплексная, поэтому призываю сосредоточиться на одной из её частей — документировании исходного кода
Я считаю, что при разработке своих классов и функций разработчик должен их документировать в формате phpDoc или сходном диалекте.
Зачем это надо
- показ человеческих подсказок по коду на уровне IDE.
- возможность посмотреть описание чужого или класса и быстро с ним разобраться.
- возможность геренации списков todo на следующую итерацию или для себя
- что я забыл?
Возможные возражения
— меня парят эти комментарии, они больше чем сами функции
— пользуйся автоматическим сворачиванием кода phpDoc в своей IDE
— нафига это надо, мой код и так понятен. Ты что, тут всё просто, я могу пояснить, что конкретно не понятно???7
- ок, у тебя 1 год работы на проекте, а «Вася» только после универа, ему на порядок труднее.
- я не хочу тратить своё время на эту фигню, давайте лучше следующую сложную клёвую задачу
- задача не считается сделаной, если нет одного из артефактов. В этом случае - документации по классам тобой написанным.
Хочется обсудить следующие вещи
1. Привить народу культуру документирования исходного кода
2. Использование инструментов генерации документации
По пункту два намедни сделал следующее
Поставил через PEAR и
phpDocumentor насколько я понял прекратил развитие, поэтому ZEND перешёл на .
Из коробки ни один и них не смог завестись с файлами проекта в кодировке windows1251. C UTF - всё ок. Стандартные шаблоны что у первого, что у вторго - абсолютно неудобные (шрифты, отступы итд).
Интересно конечно как организовано написание документации по Битриксу. Зовём Роберта. Т.к. в файлах ядра нет phpDoc шапок, то их вырезают перед релизом или вообще не используют, а документирование идёт отдельным процессом.
Есть сайт, помимо типового функционала коробки на него навёрнута интеграция с рядом сервисов, сделаны нестандартные вещи, обслуживающие специфический функционал, сайт сопровождается командой из 5+ разработчиков.
Какие проблемы могут быть
1. Трудности с подключением нового разработчика. Большой временной лаг на то, чтобы разобраться с уже реализованным функционалом.
2. Трудности с донесением изменений по архитектурной и функциональной части до других разработчиков.
3. Иногда могут возникать ошибки из-за использования устаревших функций написанных другим разработчиком, но при беглом взгляде другого вроде решающих его задачу итд.
4. Сложности при планировании новых функционалных блоков.
Проблема комплексная, поэтому призываю сосредоточиться на одной из её частей — документировании исходного кода
Я считаю, что при разработке своих классов и функций разработчик должен их документировать в формате phpDoc или сходном диалекте.
Зачем это надо
- показ человеческих подсказок по коду на уровне IDE.
- возможность посмотреть описание чужого или класса и быстро с ним разобраться.
- возможность геренации списков todo на следующую итерацию или для себя
- что я забыл?
Возможные возражения
— меня парят эти комментарии, они больше чем сами функции
— пользуйся автоматическим сворачиванием кода phpDoc в своей IDE
— нафига это надо, мой код и так понятен. Ты что, тут всё просто, я могу пояснить, что конкретно не понятно???7
- ок, у тебя 1 год работы на проекте, а «Вася» только после универа, ему на порядок труднее.
- я не хочу тратить своё время на эту фигню, давайте лучше следующую сложную клёвую задачу
- задача не считается сделаной, если нет одного из артефактов. В этом случае - документации по классам тобой написанным.
Хочется обсудить следующие вещи
1. Привить народу культуру документирования исходного кода
2. Использование инструментов генерации документации
По пункту два намедни сделал следующее
Поставил через PEAR и
phpDocumentor насколько я понял прекратил развитие, поэтому ZEND перешёл на .
Из коробки ни один и них не смог завестись с файлами проекта в кодировке windows1251. C UTF - всё ок. Стандартные шаблоны что у первого, что у вторго - абсолютно неудобные (шрифты, отступы итд).
Интересно конечно как организовано написание документации по Битриксу. Зовём Роберта. Т.к. в файлах ядра нет phpDoc шапок, то их вырезают перед релизом или вообще не используют, а документирование идёт отдельным процессом.
Изменено: Месилов Максим - 10.06.2011 14:46:07
Группы на сайте создаются не только сотрудниками «1С-Битрикс», но и партнерами компании. Поэтому мнения участников групп могут не совпадать с позицией компании «1С-Битрикс».
