Бессмертный код. Манифест ALPHA

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

Начните с того, что создайте отдельный файл (далее манифест) с расширением *.alpha в который поместите сакральные знания. Суть проста – помещайте в файл всё: требования, бизнес-правила, ограничения, уточнения, выводы и решения, предварительно проработанные форматы, структуры, прочие важные знания или определяющий их контекст. Конечно, не стоит делать бессистемную кучу, определите основные артефакты и распределите знания в привязке к ним, по приоритету или масштабу (на ваше усмотрение). В результате должно получиться примерно так …

Требования, бизнес-правила, ограничения, уточнения, выводы и решения, предварительно проработанные форматы, структуры, прочие важные знания или определяющий их контекст. ==================================================================================== #A Программа # Должна распределять все товары каталога по разделам согласно правилам (требованиям), определенных для этих разделов. #AA Товары, помещенные в особый (блокирующий) раздел (и его подразделы), не должны распространяться программой по обычным разделам. Не распространяемые товары должны удовлетворять правилам обычного раздела, в котором они могут находиться. #AB Если товар удовлетворяет требованиям раздела и ещё не помещен в него, то товар необходимо поместить в раздел. #AC Если товар НЕ удовлетворяет требованиям раздела и помещен в него, то товар необходимо изъять из раздела. #АD Если для раздела не определены правила, то товары, находящиеся в этом разделе, должны удовлетворять требованиям родительского раздела, для которого правила определены. #AE Если для раздела не определены правила, то товары в него не добавляются. #AF Товары из раздела без правил должны распределяться по подразделам с правилами. #AG Выключенные разделы тоже администрируются программой (т.к. они могут быть включены). #AH Распределению подлежат только актуальные товары. #AXA Должна выполняться максимально быстро. #AXB Должна сохранять отчет с временными метками запуска основных блоков. #B Раздел каталога # Может содержать любое количество правил. #BA Семантика объединения правил соответствует логическому "И". # Может быть более одного правила с одинаковым свойством (для работы с множественными свойствами). #C Правило # Содержит: свойство, значения свойства, правило их применения. #D Свойство # Могут использоваться только: перечисляемые и числовые свойства. #E Значение свойства в правиле # Может быть только целочисленным. #F Правило применения # Записывается в формате JSON. # Может использоваться только одна группа атрибутов: для перечисляемого свойства или для числового свойства. # Правило применения перечисляемых свойств # Атрибуты: # itemList: список идентификаторов значений, подходят товары, у которых есть свойство с хотя бы одним значением из списка. # itemExclude: список исключаемых идентификаторов значений, подходят товары, у которых нет значений свойств из списка. # Может быть указан только 1 атрибут. # Семантика применения идентификаторов значений соответствует логическому "ИЛИ". # Правило применения числовых свойств # Атрибуты: # valueFrom: минимальное значение, подходят товары, у которых значение свойства больше указанного. # valueTo: максимальное значение, подходят товары, у которых значение свойства меньше указанного. # valueEdge: правило применения пограничных значений: # -1: подходят товары со значением равным valueFrom # 0: подходят товары со значением равным valueFrom или valueTo # 1: подходят товары со значением равным valueTo # Обязательные атрибуты: valueFrom, valueEdge.

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

Оставляйте знания для себя или в знак уважения к собственному труду, ну или как признак профессионализма … поделитесь частичкой души со своим творением.

Начать дискуссию