Краткая предыстория
В 2012 году мне досталась в наследство база с сильно измененной конфигурацией УТ 10.3. Эта база дорабатывалась в течении нескольких лет многими программистами (и штатными, и франчайзи). Документации практически никакой не велось, комментарии в коде были скудны и неинформативны, пользователи внедряющие тот или иной функционал уже давно уволились, спросить было не у кого... В некоторых случаях было совершенно непонятно что и для чего делалось и как это работает... И мы решили это прекратить. Были сделаны первые шаги, которые в дальнейшем привели к созданию небольшой системы оформления разработки. Данная система уже два с лишним года успешно функционирует в нашем холдинге и с лихвой окупает время потраченное на нее.
Из чего состоит эта система?
1. Комментарии в коде
2. Справочная информация
3. Цифровые обозначения отчетов/обработок
4. Добавление/изменение объектов
5. Контроль за исполнением
А теперь детально, по пунктам:
1. Комментарии в коде
О чём пойдёт речь. Комментарии в коде делают практически все программисты. Думаю всем понятно для чего они нужны. Комментарий - это признак произведенного изменения и описание этого изменения.
В чём проблема. Часто по комментарию можно понять только одно, то что было сделано изменение :) При этом искать описание этого изменения крайне проблематично (имеется ввиду описание доработки, техзадание), я думаю многие с этим сталкивались: кто-то его сделал и где-то сохранил... надо знать это место... потом умудриться найти нужную информацию... суметь увязать с тем что фактически есть в конфигурации... а может описание и не сохранилось... плюс исполнители часто забывают обновлять информацию об изменениях и она становится неактуальной. В итоге, все эти факторы мешают быстро понять кто, что, когда делал, и что нужно сделать сейчас (и в каком месте!)... А если посмотреть на проблему глобально, то выяснится что подобное ведение дел не позволяет быстро оценить отличия вашей конфигурации от типовой, какие контуры затронуты, насколько серьёзны эти изменения и т.д...
Как обычно решается. Смотрим код, пытаемся понять отличия от типовых механизмов, пытаемся понять зачем они сделаны, а если изменения сложны и непонятны - ищем у кого бы спросить (это обычно проще чем самому заниматься исследованиями!), либо сами разбираемся... В итоге на эти "разбирательства" уходит от нескольких часов до нескольких дней, и появляется очень большая вероятность совершить ошибку!
Наше решение. Сначала прошу сравнить комментарии трех программистов (примеры из рабочей базы):
Пример 1:
// voeк 30.20.2008 begin
//----------------------
// voeк 30.20.2008 end
Пример 2:
//AТ addon [14.04.2011]
//---------------------------------
//AТ addon [14.04.2011]
Пример 3 (наше решение):
//начало-ДГ.08.04.2014. Заказчик Пономаренков П. Запись реквизита ДД_Наименование_для_сайта_прайса.
//Нужно чтобы при любой записи элемента в этот реквизит записывалось полное наименование
//(если реквизит не заполнен).
//----------------------
//конец-ДГ
Проанализируем:
1. В первом примере видно:
- где начинается комментарий и где заканчивается
- кто сделал изменения
- когда сделаны изменения (правда ошибка в дате)
2. Во втором примере видно:
- кто сделал изменения
- когда сделаны изменения
3. В третьем примере (наше решение) видно:
- где начало комментария и где он заканчивается
- кто сделал изменения
- когда сделаны изменения
- кто заказчик
- название задачи
- описание задачи
Очевидно что третий пример содержит более информативный комментарий, который в полной мере выполняет свою функцию. И самое главное, для чего собственно это всё нужно, оформляя внесенные изменения подобным образом, вы сохраняете их в одном месте. В самом надежном и доступном. В базе данных. Не в файликах Word и Excel, не в сторонних программах типа Итилиума, не в головах пользователей и программистов, а ВМЕСТЕ с вашей базой данных... И даже по прошествию нескольких лет, можно легко извлечь все изменения, провести "инвентаризацию" системы и понять как сейчас она работает!
Как реализовать:
1. Все комментарии делаем однотипными и начинаем строго с символов "//начало-" (//начало-ДГ). Таким образом можно легко найти комментарии ВСЕХ программистов. Если нужно найти комментарии только ОДНОГО программиста - в поиске задаётся "//начало-ДГ". "ДГ" - это инициалы фамилии и имени программиста.
(Примечание: а теперь представьте ситуацию где один программист пишет "begin-end", другой пишет "начало-конец", а третий вообще рисует символы ">> <... будет очень сложно их найти.)
2. Указываем дату изменения (08.04.2014.) Иногда приходится доказывать пользователям что изменения начали работать с начала апреля, а не середины мая как они думают. Или нужно понять в какой последовательности изменения появлялись.
3. Указываем кто заказывал это изменение (Заказчик Пономаренков П.). По прошествии времени, очень часто забывается кто и зачем придумал это, указание заказчика поможет восстановить в памяти эту задачу. А если вы совсем забыли, или не участвовали в её реализации, можно получить дополнительную информацию непосредственно у заказчика :)
4. Даём краткое название задаче (Запись реквизита ДД_Наименование_для_сайта_прайса). Нужно для краткого указания того что делалось, какие были изменения (1) и для идентификации задачи (2). В этом примере, по краткому названию, видно что изменения касаются определенного реквизита (а не движений по регистру накопления например). А также краткое название позволяет найти ВСЕ места, где код менялся по этой задаче (используем копирование при вставке комментария).
5. Делаем подробное описание задачи (//Нужно чтобы при любой записи элемента, в этот реквизит... и далее). Нужно для понимания того, что и для чего делалось. Для каждого изменения делается свой комментарий (но первая строка у всех одинаковая!), если требуется сделать общее описание, то оно делается в одном месте. Например:
//начало-ОС.23.10.2014. Заказчик Смирнов О. Задача по написанию публикации.
//здесь описание №1
//конец-ОС
............
//начало-ОС.23.10.2014. Заказчик Смирнов О. Задача по написанию публикации.
//здесь описание №2
//конец-ОС
............
//начало-ОС.23.10.2014. Заказчик Смирнов О. Задача по написанию публикации.
//здесь описание №3
//и
//общее описание по всей задаче, потом программист поиском по названию задачи
//найдет это описание и прочтёт.
//конец-ОС
2. Справочная информация
О чём пойдёт речь. Польза от справочной информации думаю также для всех очевидна. Есть только две маленькие проблемы: обычно справка либо не информативна, либо ее попросту нет :) В нашей фирме, справочная информация делается всегда, подробно, и чаще всего ей пользуются... программисты :)
В чём проблема. У пользователей очень часто возникают вопросы типа: "откуда берет данные отчет", "как считает эта обработка", "что проверяется в документе" и т.д. А самое интересное то, что они уже не первый раз работают с этим отчетом/ обработкой/документом... они просто забыли... или сделали вид что забыли...
Как обычно решается. Что в таких случаях делает программист? Начинает вспоминать или лезет в конфигуратор... И хорошо если это делалось недавно, или алгоритм расчета какой-то простой... А если делалось давно, например несколько месяцев назад? Сколько времени надо потратить, чтобы полностью вспомнить реализованный функционал? Иногда до нескольких часов...
Наше решение. В каждом добавленном или измененном объекте есть нами добавленная справочная информация, и именно она позволяет быстро и красиво (прям на глазах у пользователя) ответить на все интересующие вопросы!
Как реализовать. В типовые объекты (справочники и документы) мы вставляем справку выше одинэсовской. Во внешних отчетах и обработках справка содержится как в самом объекте, так в специальном txt-файле (нужен для просмотра справки без конфигуратора). См. скриншоты:
Справка в программе
Справка внешней обработки
3. Цифровые обозначения отчетов/обработок
О чём пойдёт речь. Поговорим о удобстве работы с внешними отчетами и обработками.
В чём проблема. В один прекрасный день мы поняли что у нас в базе содержится огромное количество обработок и отчетов непонятно кем и для кого написанных, и главное, непонятно что они делают. И кроме этого, с ними крайне неудобно работать. Например: звонит пользователь и говорит что у него в отчете (далее следует какое-то название, что-то вроде с продажами) не появляются какие-то данные. Ваши действия: 1. найти отчет 2. вникнуть в то как он работает 3. понять что дальше делать (менять настройки, доработать его, ничего не трогать или что-то еще).
Как обычно решается. На первом же пункте возникает ступор, понять какой из отчетов "по продажам..." (вроде это слово прозвучало) использует пользователь, иногда очень проблематично, особенно в понедельник утром :) Вы начинаете его искать, попутно еще раз пять уточняя название, потому что оказывается что подобных отчетов несколько, а еще пользователь прочёл название отчета на форме, а в программе он называется немного по-другому... В итоге вы наконец находите нужный отчет и переходите к пункту 2.
Тут начинается самое интересное, хорошо если отчет типовой или написан вами, вы хоть будете знать что он делает, а если нет? Нужно как то быстро вникнуть в его суть, можно конечно спросить у пользователя, но пользователь вдруг оказался финансовым директором и ему некогда рассказывать вам об этом отчете, и скорее всего придется лезть в конфигуратор. Открыв отчет в конфигураторе вы вдруг понимаете что... ничего не понимаете... а комментариев в коде как правило немного. А иногда чтобы ответить на вопрос пользователя - нужно очень хорошо понять принцип работы отчета, а это значит досконально вникнуть в его содержимое. И тут многим (особенно начинающим программистам) приходит в голову достаточно простое решение - взять и переписать этот отчет. Но это не всегда возможно, а иногда просто невозможно (поэтому то и ценится умение читать чужой код)... В общем решение вопроса начинает затягиваться на неопределенный срок. А тут еще пользователь вас торопит. Наконец-то разобрались, но это еще не всё, нужно еще третий пункт отработать... А через месяц.... вам опять звонит этот пользователь и снова задает этот же вопрос, и вы снова проходите по этому кругу... Да-да, так к сожалению очень часто бывает.
Наше решение.
1. Чтобы быстро идентифицировать отчет (или обработку) мы присваиваем ему трехзначный цифровой код, где первая цифра закреплена за программистом, а две последующие - номер по порядку. А также присвается буквенное наименование показывающее назначение отчета. И когда пользователь говорит вам: "Посмотрите пожалуйста 516 отчет". Вы моментально находите его по цифре "516" и при этом знаете что под цифрой "5" у вас разработку ведет программист Иванов, к которому можно при случае обратиться за разъяснением.
2. Для понимания того как работает отчет, существует справочная информация, она записывается в сам отчет, а также в txt-файл. Файл этот нужен для просмотра справки без открытия отчета в 1С. В справке подробно описывается: принцип работы отчета (1), откуда берет данные (2), как их выводит (3), какие настройки нужно сделать (4), обязательные для заполнения поля (5), различные нюансы (6). В 90% случаев справочная информация позволяет дать ответ пользователю не прибегая к открытию отчета в конфигураторе.
Как реализовать:
1. Название (1), синоним (2), имя на форме (3), название каталога (4) и название txt-файла (5) всегда должны быть одинаковы. Например: DD_UT_741_Установка_доп_прав_у_пользователей. Где: DD – название компании, UT – название конфигурации, 741 – цифровой код отчета/обработки, «Установка_доп_прав_у_пользователей» - что делает данная обработка. Для удобства копирования слова разделены не пробелами, а нижними дефисами (всё название выделяется одним кликом мыши).
2. Цифровой код состоит из двух частей: 7 – цифра закрепленная за определенным программистом, 41 – номер обработки/отчета по порядку. 1С-вские обработки (измененные типовые) начинаются с «0», обработки неизвестных программистов – начинаются с «8».
3. В каждой обработке/отчете должна быть справочная информация, которая должна быть описана в txt-файле. Также создан специальный каталог для разработчиков где хранятся каталоги с отчетами/обработками. См. скриншот:
Каталог с внешними отчетами и обработками
4. Добавление/изменение объектов
1. При разработке стараемся по максимуму использовать типовой функционал, но при этом стараясь не менять его существенно, чтобы избежать ошибок и проблем с обновлением.
2. Все новые объекты (и реквизиты) добавляются с префиксом. Префикс всегда один и тот же и не привязан к программисту, нас это сокращенное название фирмы - "ДД_". Например: «ДД_Заявка_покупателя». Благодаря префиксу мы сразу понимаем какой функционал задействован, наш или типовой. Измененные и добавленные объекты добавляются в отдельную подсистему.
3. После изменения типовых объектов (или добавления новых), таких как справочники, документы – в них добавляется справочная информация с описанием произведенных изменений. Желательно вставлять их выше типовой справки, чтобы в первую очередь читались наши изменения.
5. Контроль за исполнением
Контроль осуществляется периодически, раз в два - три месяца. Для этого выборочно открываются объекты (документы, справочники, обработки), смотрится:
- справочная информация,
- названия отчетов/обработок в каталоге
- запускается глобальный поиск инициалов/ФИО программистов
Но лучший контроль - это конечно совесть исполнителя 
поэтому желательно работать с людьми ответственными, за которыми не надо следить!
Ну и напоследок, вернемся к началу:
Нужно ли это руководителю IT... Что будет если уйдут программисты (или пользователи) "носители знаний"? Если возникнет разбирательство кто, зачем, когда внедрил функционал? Если нужно быстро провести ревизию конфигурации? Как быстро передать информацию другим специалистам?
Нужно ли это ведущему программисту... Что будет когда пользователи начнут задавать вопросы по тому функционалу который писал не он, а молодые специалисты или франчайзи? Сможет он быстро ответить на эти вопросы? А если это его доработки, то сможет ли он вспомнить то что делал полгода назад?
Нужно ли это программисту... Есть мнение что чем больше информации скрыто, тем больше ценность человека как специалиста. На деле же получается наоборот, чем больше человек скрывает информации, тем меньше с ним хотят работать, ведь быть зависимым никому не хочется, а при случае - постараются избавиться от этой зависимости. Да и профессионализм этого специалиста явно под вопросом.
Нужно ли это пользователю... Как свести к минимуму количество обращений к программистам если у пользователя элементарно нет справочной информации? Как ему максимально быстро получить ответ на свой вопрос если программисту надо много времени на то чтобы найти его?
Мы для себя давно ответили на эти вопросы. Теперь ваша очередь по новой взглянуть на них :)
Всего вам доброго!
