В это статье предлагается способ, как описать душу программного кода, его альфу и омегу, и сделать его бессмертным. Бессмертным он станет потому, что код, а также мысли и мотивы создателя, смогут понять и принять другие идущие следом. Рекомендуется для сложных решений и больших блоков.
Начните с того, что создайте отдельный файл (далее манифест) с расширением *.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.
Обратите внимание на метки с символом #, они нужны для связывания кода со знаниями (ставятся в комментариях). Конечно, для полноты картины одного манифеста недостаточно, обязательно нужны комментарии к коду, и чем больше и понятнее они, тем понятнее будут ваши мотивы и решения. Очень рискованно исправлять чужой код, если достоверно не известны все аргументы, которыми пользовался автор.
Оставляйте знания для себя или в знак уважения к собственному труду, ну или как признак профессионализма … поделитесь частичкой души со своим творением.
