Просмотров: 20735
Дата последнего изменения: 26.01.2024
Сложность урока:
3 уровень - средняя сложность. Необходимо внимание и немного подумать.
4
5
Почему нужна собственная документация
При разработке собственных решений, а также созданию проектов на Bitrix Framework с интеграцией с различными сервисами, с нестандартным специфическим функционалом крайне рекомендуется ведение собственной документации. И чем нетипичнее, крупнее, длительнее, сложнее и объёмнее проект, чем больше исполнителей над ним работает, тем более необходима документация и более обширной и разноплановой должна она быть.
Какие проблемы решает собственная документация:
- Трудности с подключением нового разработчика. Требуется довольно много времени на то, чтобы ему разобраться с уже реализованным функционалом.
- Трудности с донесением изменений по архитектурной и функциональной части до других разработчиков.
- Иногда могут возникать ошибки из-за использования устаревших функций, написанных другим разработчиком, но при беглом взгляде другого вроде решающих его задачу и так далее.
- Сложности при планировании новых функциональных блоков.
- Проблемы с поддержкой собственных решений в Маркетплейс.
Проблема комплексная, так как требует не только документирования исходного кода, но и написания документации для администраторов и пользователей. Другими словами, требуется сделать всё то, что делает вендор.
Пользовательская и администраторская документация
Самое простое в этом комплексе - это создание администраторской и пользовательской документации. Причём с администраторской документацией всё может быть ещё проще, так как есть штатная возможность системы использовать подсказки к полям компонентов.
Считается, что пользовательская документация требуется не всегда, но это не так. Нужно исходить из того, что работать с вашим проектом будут не только квалифицированные или, хотя бы, пытливые люди, но и безразличные ко всему неумёхи, которым надо всё показывать "от и до". Ну, а в больших проектах с "навороченным" нештатным функционалом от неё вообще никуда не деться.
Создание такой документации не представляется сложным этапом в работе. Её в состоянии выполнять сотрудники с уровнем "продвинутого пользователя". Здесь больше вопрос ресурсов, оплаты их труда, многие студии пренебрегают этим этапом.
Документация для разработчиков
Сложность создания документации для разработчиков имеет объективные и субъективные основания. Объективные:
- Писать её, кроме самого разработчика, некому. Сторонний неквалифицированный сотрудник не сможет детально разобраться в коде. Держать отдельно квалифицированного программиста на написании документации по чужому коду - даже не роскошь, а глупость.
- Функционал никогда не выходит не то что в неизменном, а даже в законченном виде. Поэтому написание документации, как правило откладывается "на потом" и успешно забывается.
- Неверная организация процесса разработки не оставляет времени на написание документации. При сжатых сроках и несоответствующем бюджете разработчик стремится снизить свои трудозатраты.
Субъективная причина одна: психологическое неприятие разработчиком необходимости писать документацию.
Объективные трудности должны преодолеваться за счёт правильной организации процесса разработки. Субъективные - за счёт постоянной разъяснительной работы, терпеливого убеждения.
Типовые возражения программистов по поводу написания комментариев
|
- "Меня парят эти комментарии, они больше чем сами функции."
Ответ: пользуйся автоматическим сворачиванием кода phpDoc в своей IDE.
- "Нафига это надо, мой код и так понятен. Ты что, тут всё просто, я могу пояснить, что конкретно не понятно?"
Ответ: хорошо, у тебя 1 год работы на проекте, а «Вася» только после универа, ему на порядок труднее.
- "Я не хочу тратить своё время на эту фигню, давайте лучше следующую сложную клёвую задачу"
Ответ: Задача не считается сделанной, если нет одного из артефактов. В этом случае - документации по классам тобой написанным.
Имейте в виду, что одной из причин может оказаться то, что программист просто не владеет русским языком в той же мере, что и языком программирования. И просто боится об этом сказать.
|
При разработке своих классов и функций разработчик должен их документировать в формате PHPdoc или сходном диалекте. Это позволяет:
- осуществить показ человеческих подсказок по коду на уровне IDE;
- иметь возможность посмотреть описание чужого класса и быстро с ним разобраться;
- иметь возможность генерации списков todo на следующую итерацию или для себя.
В качестве инструментов можно использовать:
При использовании любого инструмента придётся разбираться с кодировками. Это особенность, связанная с Bitrix Framework: при выставленном в настройках проекта UTF-8, в коде ядра портятся комментарии.