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