Прежде чем перейти к статье, хочу вам представить, экономическую онлайн игру Brave Knights, в которой вы можете играть и зарабатывать. Регистируйтесь, играйте и зарабатывайте!
В этой статье описывается способ, как описать программный код чтобы любой посторонний человек мог, за относительно небольшое время, его понять и, при необходимости, исправить. Это первый подход к снаряду, поэтому решение будет описано в значительной степени эскизно. Для реализации всех предложений необходима доработка IDE, никаких изменений вносить в ЯП не предполагается.
Конструкция решения
Описание кода будет располагаться в отдельном файле – манифесте. Файл будет иметь несколько секций: заголовки, ссылки на код, перечень требований, план кода.
Заголовки
В этой секции будут различные заголовки: title, description, version и т.д.
Ссылки на код
В этой секции будут ссылки на файлы кода.
Перечень требований
Эта секция заполняется разработчиком вручную. В ней должны быть перечислены абсолютно все требования и идеи, которые вы реализовали в коде. С большой вероятностью требования будут такие: бизнес-требования, функциональные требования, технические требования и ограничения, уточнения, дополнения, улучшения, в том числе, сделанные разработчиком.
Все требования должны получить собственное кодовое обозначение (буквенное), которыми будет размечен программный код. Разметка кода будет осуществляться исключительно в комментариях. Код метки предваряется символом #.
Начальный символ метки обозначает масштаб / класс требования, что очень полезно при знакомстве с задачей:
A – требование, которое относится ко всей программе. Этот тип требований не участвует в разметке программного кода, ограничен одной литерой.
B – крупное требование, которое реализуется одним или несколькими крупными блоками кода.
С – относительно небольшое требование, которое реализуется мелкими блоками кода и отдельными строками.
D – самое мелкое требование, которое реализуется в строке или внутри строки кода.
Для разметки кода используется три вида меток (php нотация, здесь и далее):
// #CC – строчная метка требования.
// ##BA – стартовая метка на блок кода.
// #BA# – финишная метка на блок кода.
Требования могут быть вложенными. Вложенность требования показывается отступом. Вложенность дает понять, что это требование является уточнением родительского требования.
Справа от требования или ниже рекомендуется размещать ссылку, ведущую к документу-источнику.
Метка требования, начиная с класса B, должна выглядеть как гиперссылка, при клике на которую должно открыться окно, в котором собраны все фрагменты кода, размеченные этим требованием, из всех связанных файлов. Оператор должен иметь возможность править код в этом окне или перейти к фрагменту в окне с полным кодом файла. Клик по метке в комментарии должен приводить читателя обратно к требованию. Наведение указателя на метку должно приводить к выводу подсказки с текстом требования и гиперссылкой на связанный документ-источник (с возможностью ей воспользоваться).
IDE должна проверять парность блоковых меток и предупреждать если обнаружена недостаточная или избыточная разметка. Вложенность одинаковых меток должна считаться ошибкой.
При исправлении кода, среда должна выделять цветом требования, в которых потенциально требуется коррекция формулировок.
Формирование перечня требований начинается до создания кода и продолжается вплоть до завершения работы с кодом. Присвоение кодовых обозначений и разметка кода производятся после завершения работы над кодом.
Пример требований
A Разработать программу генерации URL виртуальных подразделов (ВПР) к реальным разделам каталога.
DA Создавать ВПР только для актуальных разделов.
DC Создавать ВПР только у разделов для которых определены правила.
DD Создавать ВПР только для разделов с 1-го по 4-й уровень.
DE Не создавать ВПР для разделов, имена которых начинаются с подчеркивания.
DF Приводить URL к нижнему регистру.
BA Сохранять созданные URL в таблицу.
CA Не удалять старые URL.
A Реализовать максимально быстрый алгоритм.
A Реализовать алгоритм с минимальной потребностью в оперативной памяти.
План кода
Эта секция заполняется автоматически, на основании меток и комментариев, сделанных разработчиком. Польза плана в том, что читатель может быстро ознакомиться с конструкцией решения, выбирая степень детализации. Также, как и для требования, метка плана будет начинаться со специального символа #. За символом должна следовать цифра, обозначающая слой плана.
// #1 – метка первого (слоя) плана.
// #2 – метка второго плана.
// #3 – метка третьего плана.
Слоев плана может быть сколько угодно, степень детализации слоя разработчик определяет самостоятельно. Для первого плана рекомендуется использовать не более 10 меток. При открытии манифеста читатель должен увидеть только первый план, далее, при необходимости, он должен иметь возможность погрузиться в нижние слои определенного узла или всех сразу. Все последующие слои должны давать умеренно дозированную информацию о конструкции решения. Каждый новый детальный слой определенного узла — это маленькая страничка большой книги, не спешите рассказывать сразу всё.
Размечать меткой рекомендуется: циклы, конструкции ветвления потока, подписанные блоки кода.
Префикс (for, foreach, if, block и т.д.) строки плана должен выглядеть как гиперссылка, при клике на которую осуществляется переход к метке в комментарии. Клик по метке в комментарии должен приводить читателя обратно к плану.
Рекомендуется начинать писать программу так, чтобы сперва сформировался первый план решения (без уточнения нюансов в коде), затем второй и так далее. В конечном итоге все логические блоки и логические операции должны быть размечены.
Пример плана
block: входные проверки
block: установки среды
block: подключения файлов
+ block: стартовые операции, инициализация глобального контекста
+ block: основной алгоритмический блок
+ block: финальные операции
… и кода
<? php
// #1 входные проверки
∙ ∙ ∙
// #1 установки среды
∙ ∙ ∙
// #1 подключения файлов
∙ ∙ ∙
// #1 стартовые операции, инициализация глобального контекста
∙ ∙ ∙
// #1 основной алгоритмический блок
∙ ∙ ∙
// #1 финальные операции
∙ ∙ ∙
После раскрытия узла «основной алгоритмический блок» будет так
block: входные проверки
block: установки среды
block: подключения файлов
+ block: стартовые операции, инициализация глобального контекста
block: основной алгоритмический блок
foreach: обслуживание разделов каталога
+ block: инициализация контекста раздела каталога
+ foreach: построение правил создания URL
+ block: прочие подготовительные операции
+ foreach: создание URL по правилам (целевой алгоритмический блок)
+ block: сохранение результатов
+ block: финальные операции
Отступы определяются слоем плана и вложенностью в операторы.
<? php
// #1 входные проверки
∙ ∙ ∙
// #1 установки среды
∙ ∙ ∙
// #1 подключения файлов
∙ ∙ ∙
// #1 стартовые операции, инициализация глобального контекста
∙ ∙ ∙
// #1 основной алгоритмический блок
∙ ∙ ∙
foreach ($sections as & $section) { // #2 обслуживание разделов каталога
// #2 инициализация контекста раздела каталога
∙ ∙ ∙
foreach ($rules as & $rule) { // #2 построение правил создания URL
∙ ∙ ∙
}
// #2 прочие подготовительные операции
∙ ∙ ∙
foreach ($rules as & $rule) { // #2 создание URL по правилам (целевой алгоритмический блок)
∙ ∙ ∙
}
}
// #2 сохранение результатов
∙ ∙ ∙
// #1 финальные операции
∙ ∙ ∙
Прочие рекомендации
Рекомендуется снабжать код избыточными комментариями, в особо сложных случаях рекомендуется использовать две формулировки для объяснения одного и того же решения.
Излагайте в комментариях не только перевод смысла кода на человеческий язык, но и почему решение реализовано именно так, какие выгоды это дало, где использована выгода.
Связывайте различные фрагменты кода собственными требованиями-решениями.
Помните, другие люди будут не только продлевать жизнь вашему коду, но и учиться на нем.
Если кто-то захочет реализовать в своей IDE - welcome, помогу с развитием идеи.
