Стандарт SFD

Текущая версия стандарта 1.5 (изменения от 03.07.2023).

Цель стандарта: облегчить создание программ с помощью ChatGPT. Стандарт призван обеспечить консистетнтность проекта на всех этапах разработки, во всех аспектах — соблюдение единых стандартов кодирования, имён переменных и функций, сохранения целей проекта, соблюдения заданных условий реализации.

Стандарт SFD 1.5 (Streamlined Flow Description) представляет собой текстовый формат для описания программы, ее структуры и логики, с использованием четкой иерархии блоков.

Стандарт функционального описания (SFD) версия 1.5

1. Блок 1. Обзор программы: Описывает название, назначение программы, входные и выходные данные, краткое описание процесса работы и возможности и ограничения программы.
2. Блок 2. Глобальные данные: Описывает глобальные переменные и структуры данных, их назначение, структуру и использование в программе.
3. Блок 3. Общие принципы и практики: Описывает общие стилистические и технические руководящие принципы для кода, включая обработку ошибок, стиль кодирования, логирования и другие принципы, которые должны соблюдаться во всем коде.
4. Блок 4. Текстовый поток управления: Описывает последовательность выполнения функций, их взаимосвязь и взаимодействие с глобальными данными.
5. Блок 5. Блоки функций: Содержит подробное описание каждой функции, включая идентификатор, docstring, имя функции с типами аргументов и возвращаемого значения (type hints), описание входных и выходных данных, глобальных изменений, критических точек и логирования.
6. Блок 6. Верхнеуровневый код: Описывает верхнеуровневую логику программы без детализации, указывая последовательность вызова функций, глобальные данные, используемые на этом уровне, и их взаимодействие с функциями.

Детальное описание SFD 1.5

1. Блок 1. Обзор программы. В этом блоке предоставляется краткое описание программы, включая ее назначение, входные данные, выходные данные и основные этапы работы. Здесь также указываются возможности и ограничения программы, чтобы дать общее представление о том, что программа может или не может сделать.
   1. Название программы: Краткое и понятное название программы, отражающее ее основную функцию.
   2. Назначение программы: Цель и основные функции программы, описание того, что программа предназначена делать.
   3. Входные данные: Описание данных, которые программа будет принимать на вход для обработки.
   4. Выходные данные: Описание данных, которые программа будет возвращать после выполнения своих функций.
   5. Описание работы: Краткое описание основных этапов работы программы, включая основные функции, которые она выполняет, и последовательность их выполнения.
   6. Ограничения программы: Описание ограничений, связанных с работой программы, таких как поддерживаемые форматы, требования к данным или совместимость с определенными системами.
2. Блок 2. Глобальные данные. В этом блоке описываются глобальные переменные и структуры данных, используемые в программе. Указывается назначение каждой переменной или структуры данных, их структура и связь с другими элементами программы. Также описывается, в каких блоках или функциях используются эти глобальные данные.
   1. Описание глобальных переменных: Перечисление и подробное описание всех глобальных переменных, используемых в программе, включая их типы данных и назначение. Название каждой переменной начинается с $. Ссылки на эти переменные будут в блоках 3, 4 и 5.
   2. Структура данных: Описание структуры каждой глобальной переменной, включая составляющие ее элементы, их типы и связи между ними.
   3. Ограничения и требования: Описание ограничений и требований, связанных с глобальными переменными, таких как требования к размеру, формату или значениям данных.
3. Блок 3. Общие принципы и практики
   • Стиль кодирования и именование:
     • Весь код должен следовать стандарту PEP 8.
     • Все функции и переменные должны следовать стилю snake_case.
     • Глобальные переменные должны начинаться с префикса «g_».
     • Переменные должны иметь постфикс типа (например, _list, _dict, _str и т.д.).
   • Комментарии и документация:
     • Все функции и классы должны иметь строку документации (docstring), которая кратко описывает их назначение, входные параметры, возвращаемые значения и любые возникающие исключения.
     • Более сложные участки кода должны включать комментарии, объясняющие их работу.
     • Все переменные и атрибуты классов должны быть документированы.
   • Обработка ошибок:
     • Все функции и методы должны обрабатывать возможные исключения и возвращать понятные сообщения об ошибках.
     • Исключения должны быть как можно более конкретными и не должны маскировать ошибки нижнего уровня.
     • Критические ошибки, которые могут привести к остановке программы, должны быть логированы на уровне CRITICAL.
   • Тестирование:
     • Все функции и методы должны иметь соответствующие модульные тесты.
     • Все критические ошибки должны быть проверены на наличие в модульных тестах.
   • Логирование:
     • Все функции и методы должны включать соответствующие уровни логирования: DEBUG, INFO, WARNING, ERROR, CRITICAL.
     • Уровни логирования следует интерпретировать следующим образом:
       • DEBUG: подробная информация, интересная только при диагностировании проблем.
       • INFO: подтверждение того, что все работает, как предполагалось.
       • WARNING: указание на то, что что-то неожиданное произошло, или возможна проблема в будущем.
       • ERROR: более серьезная проблема, программа не смогла выполнить какую-то функцию.
       • CRITICAL: очень серьезная ошибка, программа, возможно, может не справиться с выполнением своих функций.
4. Блок 4. Текстовый поток управления. Этот блок содержит описание логики исполнения программы, включая последовательность выполнения функций, их взаимосвязь и взаимодействие с глобальными данными. В этом блоке указывается, какие функции вызываются и в каком порядке, а также как они связаны с глобальными данными и другими функциями.
   1. Описание логики исполнения: Текстовое изложение последовательности выполнения функций, включая их вызовы, порядок выполнения и взаимодействие с глобальными данными и другими функциями.
   2. Взаимосвязь функций: Объяснение, как функции взаимодействуют друг с другом, какие данные передаются между ними, и как результаты одной функции могут влиять на работу других. При этом на переменные и структуры данных ссылаются в формате $имя (в том виде, как они перечислены в блоке 2), а на блок функций: %название_блока (в том виде, как эти блоки будут перечислены в Блок 4).
   3. Использование глобальных данных: Описание того, как глобальные данные используются в рамках потока управления, как они влияют на выполнение функций и как функции могут изменять глобальные данные.
   4. Условия и ветвления: Описание условий, при которых происходит переход между функциями или ветвление потока управления, а также указание на возможные альтернативные пути выполнения программы и их последствия.
   5. Завершение: Краткое обобщение того, как поток управления влияет на работу программы, и перечисление ключевых результатов, достигаемых в результате выполнения потока управления.
5. Блок 5. Блоки функций. Блоки функций предоставляют полное и детальное описание каждой функции в программе, обеспечивая таким образом глубокое понимание ее работы и взаимодействия с другими функциями и глобальными данными. В этом блоке подробно описывается каждый блок функций, включая следующие аспекты:
   • Идентификатор блока: Уникальный идентификатор для каждого блока функций, который будет использоваться в других частях SFD для ссылки на этот блок (например, %auth, %ListOfNotes).
   • Описание функции (docstring): Подробное текстовое описание функции, включая ее назначение, входные и выходные данные, глобальные изменения, критические точки и логирование. Это должно быть написано в стиле docstring, чтобы облегчить чтение и понимание.
   • Критические точки и действия в них: В этом разделе указываются критические точки в функции (если они есть) и действия, которые выполняются в них. Может быть несколько критических точек, и каждая из них должна быть описана отдельно.
   • Логирование: Описание логирования в функции, включая уровни логирования (DEBUG, INFO, WARN, ERROR, CRITICAL), причины логирования определенных событий и цели использования логов в будущем. Может быть несколько тем для логирования, и каждая из них должна быть описана отдельно.
   • Имя функции с типами аргументов и возвращаемого значения (type hints): Указание имени функции вместе с типами аргументов и возвращаемого значения, используя type hints. Это облегчит чтение и понимание кода, а также обеспечит более строгую типизацию для функции.
   • Внутренние структуры данных: В случае необходимости, в блоке функций могут быть описаны внутренние структуры данных, которые существенны для понимания работы функции. Это может включать, например, вспомогательные переменные, списки, словари или другие структуры, которые используются внутри функции.
   • После всех блоков функций — описание взаимодействия с глобальными переменными
     • Взаимодействие с другими данными: Описание того, как глобальные переменные взаимодействуют с другими данными или структурами в программе, включая преобразования, связи и зависимости.
     • Изменения данных: Описание возможных изменений глобальных переменных в процессе работы программы, включая причины и последствия таких изменений.
6. Блок 6. Верхнеуровневый код. Блок 5 позволяет быстро понять, как весь код программы работает вместе, без погружения в детали каждой функции. Это облегчает анализ архитектуры программы и понимание ее работы в целом. В этом блоке описывается верхнеуровневая логика программы на указанном языке (по умолчанию, python), без имплементации функций, только с их вызовами, согласно блокам 2, 3 и 4. Он включает следующие аспекты:
   1. Импорт библиотек: В начале блока указываются все необходимые библиотеки и модули, которые используются в программе. Это облегчает понимание зависимостей программы и обеспечивает возможность проверки совместимости.
   2. Глобальные данные: В этом разделе определяются глобальные данные, используемые на верхнем уровне программы. Это может включать переменные, константы и структуры данных, которые описаны в блоке 2 (Глобальные данные).
   3. Последовательность вызова функций: Здесь описывается последовательность вызова функций согласно блоку 3 (Поток управления). Для каждой функции указывается ее имя, аргументы (если есть) и результаты, получаемые после выполнения функции. Это помогает понять, как функции взаимодействуют между собой и как их вызов влияет на глобальные данные.
   4. Взаимодействие с глобальными данными и функциями: В этом разделе описывается, как верхнеуровневый код взаимодействует с глобальными данными и функциями, определенными в блоках 2 и 4. Это включает изменение глобальных данных, вызов функций и получение результатов от них.

Протокол внесения изменений в блоки описания программы
Внесение изменений в любой из блоков описания программы. «Я хотел бы добавить/изменить блок %block_name для %reason. Как это изменение повлияет на общую структуру кода и другие блоки?»b. «Можешь ли ты обновить блок ‘Поток управления’ и/или верхнеуровневый код, чтобы учесть это предлагаемое изменение?»c. «Можешь ли ты помочь мне разработать новый/измененный блок %block_name, включая все необходимые детали (входные данные, выходные данные, функции и т.д.)?»d. «Пожалуйста, проверь и утверди изменения, которые мы сделали в блоке %block_name, и обнови все связанные блоки и документы.»
После внесения всех изменений, я задаю вопрос: «Можешь ли ты предоставить мне обновленное описание измененных блоков SFD, чтобы я мог обновить свою сохраненную копию и ссылаться на актуальную информацию при дальнейшей разработке?»