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

Разделение архитектуры приложения на слои позволяет

• лучше выполнять декомпозицию задачи
• проще ориентироваться внутри проекта
• разработчики приобретают возможность внесения изменений в какой-то определённый слой, вместо того, чтобы перерабатывать всё приложение целиком
• помогает структурировать приложения разложением на группы подзадач, находящихся на определенных архитектурных слоях
• в зависимости от уровня сложности слоя, к опыту разработчиков могут быть разные требования, что позволяет распределять разработчиков по слоям в зависимости от опыта

В крупных системах так или иначе слои используются, даже если их так никто не называет.

В чём сейчас заключается путаница:

• принято считать, что слоёв должно быть 3: данные, бизнес-логика, интерфейса но на самом деле слоёв может быть любое необходимое количество
• нет критериев, по которым те или иные задачи относятся к тому или иному слою, что часто приводит, к созданию одного большого прикладного слоя, либо один какой либо из слоёв дорабатывается под задачи, не характерные для него
• нет конкретного короткого определения
• есть пересечения между понятиями слоя (layer), уровня и яруса (tier), к которым так же нет точных определений. По Фаулеру уровни относятся, подразумевая физическое разделение, а на практике такой определённости нет

Цель этой статьи в том, чтобы совместно выработать определённость, создать у всех единое представление и выбработать короткое, ясное и практичное определение для данных понятий. Всё что приводится в статье вы можете обсудить и дополнить в комментариях, а я актуализирую материал в статье в соответствии с замечаниями.

Вместо понятий слой приложения и уровень абстракции пусть используется понятие Архитектурный слой.

Архитектурный слой это определённый (огранниченный назначением, замкнутый) набор ресурсов (инструментов работы с ресурсами, деталей, составляющих), с помощью которых реализуются множество (огранниченное критериями) прикладных задач, характерных для данного слоя. Вышестоящий слой реализует свои составляющие (ресурсы), на основе ресурсов нижестоящего слоя. Ресурсы определённого слоя совместимы друг с другом и используются только внутри этого слоя (в идеале). Вышестоящий слой может созадавать свои ресурсы используя ресурсы нескольких слоёв. Может иметь отношение к абстрактной, идеализированной системе, сущетвующих в виде схем либо в большей мере относится к реализации это определяет составляющие слоя.

Составляющие слоя:

• если слой относится к реализации: классы, объекты, контекст, сервисы, контроллеры, прокси, сборки ...
• если слой относится к абстракции: модели данных (идеализированные), действия...

Чем характеризуется архитектурный слой:

• прикладное назначение, конкретное, логичное, определяет множество задач, которые можно отнести к определённому слою
• определённое множество задач, реализуемых на данном слое
• ресурсы и инструменты, с помощью которых реализуются задачи: данные, объекты и действия, которые можно выполнить над данными и объектами
• данные и логика внутри определённого слоя согласованы внутри себя
• согласованность определяет предсказуемость и предопределённость во взаимодествии ресурсов определённого слоя, другими словами, детали из которых образуется слой совместимы сдруг с другом
• отдельный слой можно воспринимать как единое самодостаточное целое
• зависимость между слоями можно свести к минимуму
• созданный слой может быть основой для нескольких различных слоёв более высокого уровня
• при переходе от одного слоя к другому, моделируемые сущности обычно подвергаются преобразованию из одного представления в другое

Коротко о порядке проектирования архитектурных слоёв:

1. Выделяется все бизнес требования, которые структурируются по категориям.
2. Требования разбиваются на задачи, которые должны решаться приложением.
3. Задачи категоризируются и объединяются в группы на основе схожести своего предметного назначения.
4. На основе этих категорий выделяется общее назначение архитектурного слоя, в котором будут решатся задачи.
5. Решения задач можно представить как алгоритм, или процесс, который обеспечивает желаемый результат. Из всех задач выделяются общие составляющие (детали), из которых они реализуются. (модели и действия над ними). О том как это делается, будет дополнительная статья.
6. На основе выделенных составляющих реализуются классы соответствующего слоя и как правило объединяются в одну отдельную сборку.

Пример 1.
Модель ISO/OSI

Пример 2.
Стоит задача автоматизировать электронный документооборот, которая подразумевает
выполнение элементарных действий с различными видами документов: подписание, согласование, отправка и другое
автоматическая фоновая работа в несколько потоков
управление работой потоков оперативно через пользовательский интерфейс
обмен данными с другими системами (приём, отправка, конвертирование документов)


Пример 3.
Строительство офиса
1 уровень задачи по строительству здания, фундамент, возведение стен, кирпичи, цемент
2 уровень отделка мебелирования, детали обои, мебель
3 уровень логическое распределение помещений, людей, деление на отделы детали: отделы, рабочие места, помещения

Составляющие (реусуры) слоя, включают в себя объекты (кирпичи, плиты, цемент) и действий над ними (положить, установить).

Один слой предоставляет только набор тех ресурсов, которые ему логически характерны. 3й слой (места, кабинеты, отделы), работает только в рамках этих сущностей и действий. Если мест не хватает, то кабинет не достраивается, но его можно достроить, доработав ниже стоящий слой.

Данная статья посвящена разбору вопроса о том, какому именно объекту ООП должен принадлежать метод, осуществляющий взаимодейстие между несколькими сущностями.
Это распространённая тема для холиваров. Например:

Не используйте ООП. Никогда. Это ошибка.
На эту тему есть много материалов, к примеру: www.youtube.com/watch?v=QM1iUe6IofM

Если ООП все еще кажется вам хорошей идеей, то решите простую задачку:
Есть три объекта: кошка, кормушка и человек. Вам необходимо написать метод, который бы позволял человеку покормить кошку, воспользовавшись кормушкой.
Вопрос: методом какого класса будет являться метод.покормить()?
Просьба привести аргументированный ответ, в соответствии с иерархией классов, и другими лучшими практиками ООП.

Теперь сравните это с функциональной реализацией:
У вас есть функция покормитьКошку() принимающая в качестве аргумента ссылку на кошку и кормушку.

Цитата из холивара

Как ответить на данный вопрос?
Вначале давайте рассмотрим пример из физики.

Кейс 1 (из физики): закон Ома

Закон Ома: I=U/R, где I сила тока, U напряжение, R сопротивление.

Несложно заметить, что закон Ома, как и любую другую формулу из трех переменных, можно записать тремя способами: I=U/R, R=U/I, U=IR. Как выработать правило, позволяющее однозначно определить единственную форму записи? Очень просто: надо записать с левой стороны производную величину, т.е. ту, которая становится имеющей определённое значение, в зависимости от остальных величин.

I=U/R Сила тока СТАНОВИТСЯ равной отношению напряжения на концах проводника к сопротивлению проводника верно.

U=IR Напряжение на концах проводника СТАНОВИТСЯ равным его сопротивлению, умноженному на силу тока через проводник не верно.

R=U/I Сопротивление проводника СТАНОВИТСЯ равным отношению напряжения на концах к силе тока не верно.

Видите как только мы условились, что производное значение находится слева, остался только один вариант.

Вот так же, мы поступим и в ООП. Условимся, что метод принадлежит тому, кто воздействует:

Кто_действует.Метод(Объект_воздействия);

Кейс 2: Кто взял Измаил?

Следовательно, при ответе на вопрос Кто взял Измаил? с точки зрения объектно ориентированного программирования, и с позиции кто воздействует?, правильный ответ будет Суворов.ВзятьКрепость(Измаил, Турки):boolean. Все другие варианты, такие как: Турки.Про***тьКрепость(Измаил, Суворову), Измаил.СменаСобственника(Турки, Суворов), АбстрактнаяКрепость.БытьЗахваченной(Исмаил, Суворов, Турки) и т.д. все эти варианты не верны.

Кейс 3: Человек, кормушка и кошка

Покорми кошку! с сайта corchaosis.ru

Человек насыпал еды в кормушку. Это метод: Человек.НасыпатьЕдыКошке(ПакетЕды, Кормушка). При выполнении метода, в глобальной переменной ПакетЕды количество еды уменьшается, а в глобальной переменной Кормушка появляется.

А как же кошка? А кошка существует ДО вызова метода НасыпатьЕдыКошке, как условие его вызова. Если кошка на даче, то и метод НасыпатьЕдыКошке вызываться не будет.

Кейс 4: Игрок в DOOM, шотган и монстр

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

Игрок (либо, Игрок_1 в многопользовательской игре).Выстрел(Монстр_1)
Внутри реализации метода Выстрел, мы видим, что текущее оружие игрока шотган.
Следовательно, вызываем метод вложенного объекта: Игрок_1.Оружие[Игрок_1.Номер_выбранного_оружия].Выстрел(Монстр_1)

Игрок_1.Оружие это класс TWeapon.
В данном случае, вызывается метод класса TShotgun, который является дочерним к TWeapon.
Итак, имеем: Шотган.Выстрел(Монстр_1)

Шотган, при выполнении данного действия, изменяет внутреннее состояние: для шотгана это количество патронов (а для другого вида оружия могла бы быть, например, и температура). Также, мы определяем силу урона так, шотган стреляет по 2 патрона, но может выстрелить и один, если в заряде остался только один патрон.

Если бы мы выстрелили из ракетницы, то появился бы новый объект ракета. Со своим методом Tick, обрабатывающим действия за один тик игрового времени (игровое время изменяется, обычно, в тиках). Но мы выстрелили из оружия, поражающего без задержки, поэтому знаем количество выстреленных патронов (1 или 2), знаем расстояние (сравнивая Игрок.Position и Монстр_1.Position), и внутри метода класса Шотган, рассчитываем ущерб.

И, наконец, Монстр_1.НанесёноПовреждение(сила_повреждения:Float). Теперь, как и перед этим шотган менял внутреннее состояние (кол-во патронов), теперь Монстр_1 меняет внутреннее состояние Монстр_1.Здоровье, и сценарий поведения (особенно, если Здоровье стало меньше нуля).

Итак, мы видим, что благодаря ООП, мы можем легко добавить новое оружие: достаточно описать его как дочерний класс от TWeapon, определить Выстрел и разместить на карте. Класс Игрок уже умеет подбирать и добавлять в свой игровой набор объекты TWeapon. Всё. Хотя нет, не всё. Если оружие будет дарить монстрам цветочки, заставляя их влюбляться в игрока, то и монстрам следует прописать метод ОтветитьНаПризнаниеВЛюбви:boolean, а также набор других методов в зависимости от степени проработки, в этом случае вам может потребоваться и ряд новых ООП объектов и их методов.

Кейс 5: Потрогать руками это функция или метод

Не только ответ на этот вопрос, но и сам интерфейс взаимодействия, очевидно, находится в зависимости от трогаемого объекта.

Потрогать_руками:: дом это функия.

Потрогать_руками:: ноутбук это метод объекта ноутбук. Вы должны использовать интерфейс, чтобы вызвать методы ноутбука KeyDown, KeyUp, KeyPressed передав в эти методы правильные данные: какая кнопка была нажата, в какой момент времени и т.д.

Потрогать_руками:: огонь это метод объекта вы. Вам необходим объект self, изменение состояние которого правильно опишет ожог руки. Огонь состояния не изменит.

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

Статистический подход к объяснению ошибочных дедлайнов в инженерных проектах

Кем бы вы ни были джуниором, сениором, менеджером проекта или менеджером верхнего звена с двадцатилетним опытом оценка времени проекта разработки ПО никогда не бывает простой задачей. Никто, вне зависимости от его опыта и гениальности, не может утверждать, что знает точное время завершения программного проекта.

Эта проблема особенно актуальна в проектировании ПО, но и в другие инженерные дисциплины страдают от того же. Поэтому хотя в этой статье говорится о проектировании ПО, она в некоторой степени относится и к другим дисциплинам.

Общая информация

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

Проблема

Программные проекты редко укладываются в дедлайн.

Последствия

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

Известные причины

• Неправильная оценка времени (основная тема этой статьи).
• Нечётко сформулированные на старте проекта требования с их последующим изменением.
• Украшательства: слишком много внимания уделяется деталям, не относящимся к сути проекта.
• Недостаточно времени уделено этапу исследований и проектирования архитектуры. Или наоборот уделено слишком много времени.
• Недооценка потенциальных проблем интеграции со сторонними системами.
• Стремление сделать всё правильно с первого раза
• Параллельная работа над слишком большим количеством проектов или отвлечение (слишком частое прерывание потока).
• Несбалансированное соотношение качества и производительности.

Чрезмерный оптимизм, эффект Даннинга-Крюгера, чистая неопределённость или просто математика?

Пятая стадия: ПРИНЯТИЕ.

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

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

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

Существует ли в этом безумии методика? На самом ли деле это самый лучший способ решения задач? Я не думаю, что это так, поэтому решил отправиться на поиски рационального математического объяснения тому, почему все эти умные люди не могут оценить время, которое понадобится им на выполнение работы.

Это просто математика!

Однажды я выполнял задачу, которая должна была занять 10 минут, но в конечном итоге потребовала 2 часа. Я начал размышлять о том, почему решил, что она должна занять 10 минут, и как это число выросло до 2 часов. Мой мыслительный процесс был довольно интересным:

• Я считал, что это займёт 10 минут, потому что в голове на 100% знал код, который нужно написать.
• Написание кода и в самом деле потребовало примерно 710 минут. А потом потребовалось 2 часа из-за совершенно неизвестного мне бага во фреймворке.

В управлении проектами подобное любят называть форс-мажором внешними неконтролируемыми причинами задержки.

Вероятно, вы сейчас думаете, что этим примером я подтвердил аргумент о неопределённости планирования. На самом деле, и да, и нет. Давайте взглянем чуть издалека. Да, действительно, неопределённость стала корневой причиной задержки этой конкретной задачи, потому что я бы ни за что не догадался, что такой баг существует. Но должна ли она отвечать за задержку всего проекта?

Здесь нам нужно провести границу между одиночной задачей, нерепрезентативной для всего процесса, и наоборот.

Как мы оцениваем время в нормальных условиях

Нормальное распределение (гауссиана)

Нормальные распределения встречаются повсеместно и человеческий мозг хорошо с ними освоился. Мы специалисты в оценке процессов, по своей природе следующих нормальному распределению; это основа получения знаний из опыта.

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

Я имею в виду, что не имеет смысла говорить 15 минут, потому что это редкий случай, или 7 минут, если только на улице нет дождя. И с большой вероятностью вы окажетесь правы. Если в 18 из 20 случаев путь занимал 5 минут, то определённо существует высокая вероятность, что он займёт 5 минут (медиана) и на этот раз. Вероятность примерно равна 90% (если, разумеется, не вдаваться в более сложные вычисления).

Но график искажён!

Даже если вы хорошо умеете оценивать время на выполнение задачи, это не значит, что вы хорошо оцените время на завершение проекта! Это контринтуитивно, но вы можете ошибиться сильнее.

Все читающие статью нерды-математики (и дата-саентисты/статистики) уже должны были узнать в крошечном графике из предыдущего мема скошенное вправо нормальное распределение. Увеличим его и объясним, что оно означает:


Для этой отдельной задачи медиана (median) по-прежнему имеет более высокую вероятность, чем среднее (mean)! Если вы попытаетесь угадать значение моды (mode), имеющей наивысшую вероятность, то при увеличении объёма задачи ошибётесь ещё сильнее

Видите, что здесь может пойти не так? Наша естественная догадка основана на медиане, максимизирующей вероятность правильной догадки, однако реальное число при выполнении события достаточное количество раз всегда будет стремиться к среднему. Другими словами: чем больше похожих задач вы выполняете, тем сильнее накапливается эта погрешность!


Уравнение задержки на основании этой гипотезы

Задачи программирования в проекте обычно довольно похожи друг на друга или, по крайней мере, сгруппированы в несколько похожих кластеров! Из этого уравнения также следует, что эта проблема масштабируема! Хоть мы и хотим, чтобы всё в программных проектах было масштабируемым, проблемы явно не приветствуются.

Как же воспользоваться этим знанием?

Честно говоря, в процессе написания статьи я не планировал давать рекомендаций на основании этой гипотезы. Она должна была стать просто объяснительным анализом, завершающимся гипотезой, интерпретировать которую читатель должен по собственному желанию.

Однако я понимаю, что многие будут разочарованы такой незавершённостью, поэтому расскажу, что из этого вынес лично я.

1. Проще сказать, займёт ли задача X больше/меньше/столько же времени по сравнению с задачей Y, чем точно определить, сколько займёт их выполнение. Так получается, потому что если скошенность кривых приблизительно одинакова (что справедливо для похожих задач), то сравнение медиан даёт примерно такие же результаты, как и сравнение средних.
2. Я не запоминаю и не записываю каждую отдельную задачу, чтобы проводить вычисления и получать среднее (и не могу найти никаких данных для таких опытов). Поэтому я обычно оцениваю неизбежную погрешность (среднее-медиана) как процент от времени на задачу, который увеличивается/уменьшается в зависимости от того, насколько я освоился со средой разработки. (Нравится ли мне этот язык/фреймворк (40%) Есть ли у меня хорошие инструменты отладки? (30%) Хороша ли поддержка IDE? (25%) и т.д.).
3. Я начал разделять спринты на задачи равного размера чтобы обеспечить некую однородность процесса оценки времени. Это позволяет мне воспользоваться пунктом 1. Бывает легко определить, что две задачи примерно равны по времени. Кроме того, это делает задачи ещё более похожими на то, к чему применима гипотеза, и всё становится более предсказуемым.
4. Применив эти принципы, при наличии ресурсов можно организовать тестовый прогон. Например, если за X1 дней Y1 разработчиков выполнило Z1 однородных задач, то мы можем вычислить X2 (дней), зная Y2 (количество имеющихся разработчиков) и Z2 (общее количество оставшихся задач).

---

На правах рекламы

Эпичные серверы для разработчиков и не только! Недорогие VDS на базе новейших процессоров AMD EPYC и NVMe хранилища для размещения проектов любой сложности, от корпоративных сетей и игровых проектов до лендингов и VPN.

Время идет, планета крутится, системы растут и развиваются, а я продолжаю слышать в кругах аналитиков сожаление: Эх, пришел на проект, а тут никакой документации, смотрим в код.

Но это ерунда. Хуже, когда заказчик говорит: Создали два разработчика. Уволить не могу, хотя почти ничего не делают, только по мелочи донастраивают. А с этой системой у нас уже и бухгалтерия интегрирована, и Документация? Нет ее. А надо?.. Спасите-помогите!

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

Что это за зверь документация?

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

По сути, документирование это процесс описания идеи от момента ее возникновения в сознании до выпуска результатов в в релиз. А значит документировать мы начинаем в момент написания ТЗ, при описании задачи, без строгого формата, в картинках или на листе бумаги. Когда мы формализуем, как это должно работать.

Для кого документировать?

Если нет понимания, кому нужна проектная документация, то она не нужна. Возможно, прочитав эту статью чуть дальше, мнение может резко поменяться, но это не точно.



В первую очередь документация нужна команде разработки и заказчику.

Разработчик быстрее осознает, над чем он вообще трудится, спокойнее принимает чужое наследство.

Тестировщик каждый раз не находит одни и те же ошибки, которые на самом деле уже стали особенностями реализации.

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

Иногда проектная документация нужна просто потому, что так сказали.

На мой взгляд, это самый омерзительный случай страдают все: и те, кто пишет документацию нудно, скучно, бессмысленно потраченные силы на соблюдение каких-нибудь ГОСТов, и те, кто потребляет ее обязанность заказать и оплатить документацию по ГОСТу, потому что так надо.

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

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

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

Причины, по которым компании приходят к внедрению документирования

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

Есть сервис МойСклад и 2007 год. Прекрасный пример стартапа от двух разработчиков. Фундамент сервиса был целиком заложен Аскаром (генеральный директор) и Олегом (технических директор). Если почитать историю создания МоегоСклада, то можно узнать интересный факт уже тогда было неосознанное документирование продукта в рабочей тетрадке в клеточку!

Любые знания, зафиксированные на материальном или цифровом носителе, представляют из себя ту самую проектную документацию, которая впоследствии помогает устанавливать причины: почему эта кнопка работает именно так, а не иначе.



На момент, когда у продукта было 0 пользователей, лэндинг и рабочая альфа-версия, документировать было бессмысленно. Да и сейчас любой самостоятельной команде разработчиков, запускающих стартап, уверена, документировать не надо вы сами творите свое сокровище и знаете его. Лучше докрутить еще парочку фич, чем заниматься печатью лишних символов с описанием системы для себя. Время бесценно. А вот тем, кто заказывает разработку стартапа, я советую задуматься, в какой момент они могут пожелать заменить подрядчика и начинать строить свою команду.

Пример с автомастерской

Есть среднестатистическая мастерская с механиком, которому регулярно привозят примерно одинаковые машины.

В зависимости от опыта он успешно будет чинить обычные автомобили: не глядя в инструкции, не советуясь со старшим мастером. Интуиция спасет его.

Так и с программными системами. Для опытного разработчика они все примерно одинаковые, только работают немного по-разному и названия отличаются.



Привезут в автомастерскую сломанную буханку. Опытный механик постучит молотком по нужным частям, и она поедет. А постучит возможно даже наугад! Это сопоставимо с тем, что опытный разработчик придет в разработку простой системы и будет решать задачи как получится, наугад. И все будет получаться, потому что никаких сложных связей и соединений внутри нет (например, какой-нибудь интернет-магазин с информационным сайтом или что угодно другое).

Привезут в автомастерскую сломанную буханку. Опытный механик постучит молотком по нужным частям, и она поедет. А постучит, возможно, даже наугад! Это сопоставимо с тем, что опытный разработчик придет в разработку простой системы и будет решать задачи как получится, наугад. И все будет получаться, потому что никаких сложных связей и соединений внутри нет например, какой-нибудь интернет-магазин с информационным сайтом или что угодно другое.

Привезут в автомастерскую опытному механику какой-нибудь Hyundai Solaris. Даже если он последнего года выпуска, даже если механик его впервые видит и до этого работал на Volkswagen, он не растеряется и, применив интуицию, починит его.

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

И все успешно получится, потому что система обычная, никаких наворотов нет.



Но вот привезли Aston Martin или Ferrari. А я обычный механик в среднестатистической автомастерской. Конечно, сначала я обрадуюсь такому. Но потом, когда дело дойдет до ремонта, я буду вдумчиво смотреть на это чудо света и искать все возможные инструкции, чтобы устранить неисправность.

Так и с программной системой! Приходящие разработчики видят нечто и пытаются понять, как с этим жить. Большая часть рабочего времени уходит на погружение в контекст: вдумчивый осмотр и изучение, а не на саму разработку.

Необходимость внедрения процесса документирования зависит от сложности системы.

Если система простая, то документировать необязательно. Но если внутри нее, под капотом, какой бы простой она не казалась для пользователей, появляются архитектурно сложные решения, то документирование становится важной необходимостью.

В отсутствии проектной документации основная стоимость разработки будет потрачена на изучение того, как оно работает, что это и почему так.

За 13 лет МойСклад смог очень круто подрасти: веб-приложение для RU- и US-площадок, кассовое ПО для трех платформ, мобильные приложения, шесть протоколов API и много-много всего.

Продукт простой снаружи, для пользователя, но сложный внутри для разработки и развития. Я, как ведущий системный аналитик, шла в компанию с желанием описать все быстро и продолжать развивать документированный продукт.

Когда я открыла капот дорогого и любимого Aston Martin, я поняла, что взяла очень интересную и сложную машину. Сначала было длительное изучение начинки, а теперь нужно время, чтобы успевать и развивать новое, и описывать ранее созданные детали.

Одна из основных причин начала накопления знаний в МоемСкладе продукт стал большим и сложным.

Настал момент, когда пора документировать. Этот процесс начался еще три года назад тестировщиками, которые описывали все особенности реализации и ключевые моменты поведения системы после выпуска очередной задачи в релиз.

Причиной запуска такой деятельности стало то, что ведущий QA тратила много времени на обучение продукту новых сотрудников и рассказы про одно и то же. Да и некоторые знания забываются и теряются, потому что есть золотое правило не трогай то, что работает.
Собранные командой тестирования документы и сегодня помогают ориентироваться в том, как работают части МоегоСклада: что считать нормой, а что нет.

Программный код и есть документация

Так говорят разработчики. И нет, это не так.

Во-первых, не все любят вникать в чужой код, а особенно, если это наследство досталось не от самого пряморукого разработчика. Поэтому, если ваша команда настаивает на том, что документировать не надо, то могут всплыть подводные камни.

Во-вторых, не все умеют читать программный код, и он не раскрывает ожидаемый результат. Команда тестирования, которая принимает задачи на проверку, должна понимать, какой реакции ждать от системы. В обязанности тестировщика не входит чтение программного кода. Поэтому когда он погружается в контекст задачи, по требованиям может быть понятно, как должна работать новая функциональность, но совершенно непонятно, чего ждать от ранее реализованной. Проектная документация может устранить лишние вопросы.

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

Как нас много

Как масштаб проекта по части количества людей влияет на необходимость появления документации.











Сервис МойСклад начинался с Аскара и Олега 13 лет назад. Целиком знают продукт всего три человека: Аскар, Олег и Максим присоединившийся к ним немногим позже продакт и бизнес-аналитик.

Сегодня компания насчитывает более 150 человек. Три хранителя знаний на тридцать сотрудников? Возможно. А на команду от ста человек? Да и помнить все детали, особенно когда реализовывал их не ты, просто невозможно. Поэтому нормой стал ответ смотри как на проде.

Если каждый новый сотрудник будет начинать уточнять как работает та или иная часть системы при получении новой задачи, то он будет отнимать время у коллег. Изменению подвергаются самые разные части Склада. Не всегда удается установить их истинное поведение, которое задумывалось изначально.

Баг или фича?

Может ответить только зафиксированное знание, которое либо есть, либо нет, либо оно в человеке (а значит его нет).

В МоемСкладе стали важными такие умения, как археология по коду у разработчиков, археология по возможностям системы у тестировщиков и аналитика.

Эти навыки стали ключевыми и их стоило вносить в описание вакансий. Ими обладают далеко не все на рынке труда, да и никто особо этим заниматься не хочет.

Не храните знания в людях это опасно

Рынок IT-специалистов очень бодр и динамичен. Отсутствие документации на продукт может быть опасным. Человек, уходя из компании, уносит с собой знания о тех частях, которые он делал. Это плохо тем, что развитие и сопровождение неизведанных частей становится очень дорогим удовольствием нужно исследовать, как работает сейчас и достраивать над текущим поведением нечто новое.

У бизнес-заказчика при смене подрядчика возникнет очень много вопросов с передачей кода новой компании: наследство не любят, особенно, недокументированное. Бизнес-заказчику без документации может быть сложно стать независимым.



Сегодня все более актуальна тема с удаленной работой, да и ранее команды разработки всегда обсуждали задачи в чатах (Slack, Telegram, Skype и т.д.).

В какой-то момент жизни продукта может настать перевес: переписки у разработчиков занимают больше рабочего времени, чем решение задач.

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

Моя позиция такова: стараюсь минимизировать развернутые ответы на вопросы в чатах и максимально ссылаться на существующую документацию:

Разработчик: [Вопрос]
Я: [ссылка на Confluence] п. [название]

Это куда быстрее, чем каждый раз отвечать всем на одни и те же вопросы. Если вопрос возник, значит ответ на него надо документировать. Такая вот простая логика.

И про контекст

Итого: где же тот самый момент?

Взгляните на продукт и оцените его масштаб со всех возможных сторон. Если он становится большой и сложный, то кажется, пора начинать внедрять процесс его описания.

Процесс документирования нужен далеко не всегда и это нормально.

Некоторые компании начинают с первых дней, а некоторые тянут до последнего. Но начинать никогда не поздно. Через 5 лет, через 10 или 13 главное не пытаться прятать голову в песок, когда становится заметно, что сотрудникам сложно работать и есть проблемы с пониманием системы.

Что может дать наличие документации на программный продукт?

• Меньше обсуждений в чатах и поисков причин почему так.
• Быстрее погружение в контекст.
• Команде проще понимать и оценивать объем изменений для новых задач.

А такой результат влечет за собой как минимум экономическую выгоду.

Ссылки

analystdays.ru/ru/talk/83497 Analyst Days. Как мы процесс документирования внедряли
habr.com/ru/company/moysklad/blog/452016 Сервис МойСклад 12 лет в облаке (уже 13!)