35  /  36

Документация к собственным разработкам

Просмотров: 24553
Дата последнего изменения: 26.01.2024
Сложность урока:
3 уровень - средняя сложность. Необходимо внимание и немного подумать.
1
2
3
4
5

  Почему нужна собственная документация

При разработке собственных решений, а также созданию проектов на Bitrix Framework с интеграцией с различными сервисами, с нестандартным специфическим функционалом крайне рекомендуется ведение собственной документации. И чем нетипичнее, крупнее, длительнее, сложнее и объёмнее проект, чем больше исполнителей над ним работает, тем более необходима документация и более обширной и разноплановой должна она быть.

Какие проблемы решает собственная документация:

  1. Трудности с подключением нового разработчика. Требуется довольно много времени на то, чтобы ему разобраться с уже реализованным функционалом.
  2. Трудности с донесением изменений по архитектурной и функциональной части до других разработчиков.
  3. Иногда могут возникать ошибки из-за использования устаревших функций, написанных другим разработчиком, но при беглом взгляде другого вроде решающих его задачу и так далее.
  4. Сложности при планировании новых функциональных блоков.
  5. Проблемы с поддержкой собственных решений в Маркетплейс.

Проблема комплексная, так как требует не только документирования исходного кода, но и написания документации для администраторов и пользователей. Другими словами, требуется сделать всё то, что делает вендор.

  Пользовательская и администраторская документация

Самое простое в этом комплексе - это создание администраторской и пользовательской документации. Причём с администраторской документацией всё может быть ещё проще, так как есть штатная возможность системы использовать подсказки к полям компонентов.

Считается, что пользовательская документация требуется не всегда, но это не так. Нужно исходить из того, что работать с вашим проектом будут не только квалифицированные или, хотя бы, пытливые люди, но и безразличные ко всему неумёхи, которым надо всё показывать "от и до". Ну, а в больших проектах с "навороченным" нештатным функционалом от неё вообще никуда не деться.

Создание такой документации не представляется сложным этапом в работе. Её в состоянии выполнять сотрудники с уровнем "продвинутого пользователя". Здесь больше вопрос ресурсов, оплаты их труда, многие студии пренебрегают этим этапом.

  Документация для разработчиков

Сложность создания документации для разработчиков имеет объективные и субъективные основания. Объективные:

  • Писать её, кроме самого разработчика, некому. Сторонний неквалифицированный сотрудник не сможет детально разобраться в коде. Держать отдельно квалифицированного программиста на написании документации по чужому коду - даже не роскошь, а глупость.
  • Функционал никогда не выходит не то что в неизменном, а даже в законченном виде. Поэтому написание документации, как правило откладывается "на потом" и успешно забывается.
  • Неверная организация процесса разработки не оставляет времени на написание документации. При сжатых сроках и несоответствующем бюджете разработчик стремится снизить свои трудозатраты.

Субъективная причина одна: психологическое неприятие разработчиком необходимости писать документацию.

Объективные трудности должны преодолеваться за счёт правильной организации процесса разработки. Субъективные - за счёт постоянной разъяснительной работы, терпеливого убеждения.

Типовые возражения программистов по поводу написания комментариев

При разработке своих классов и функций разработчик должен их документировать в формате PHPdoc или сходном диалекте. Это позволяет:

  • осуществить показ человеческих подсказок по коду на уровне IDE;
  • иметь возможность посмотреть описание чужого класса и быстро с ним разобраться;
  • иметь возможность генерации списков todo на следующую итерацию или для себя.

В качестве инструментов можно использовать:

При использовании любого инструмента придётся разбираться с кодировками. Это особенность, связанная с Bitrix Framework: при выставленном в настройках проекта UTF-8, в коде ядра портятся комментарии.


6
Курсы разработаны в компании «1С-Битрикс»

Если вы нашли неточность в тексте, непонятное объяснение, пожалуйста, сообщите нам об этом в комментариях.
Развернуть комментарии