Как эффективно документировать код в большом проекте на фреймворке FastAPI, в котором имеется более тысячи строк с минимальным количеством документации и всё сосредоточено в одном файле? Я стремлюсь не просто к генерации названий функций и их сигнатур, а к тому, чтобы каждая функция содержала краткое описание своего назначения. Понимаю, что для этого могут понадобиться ИИ модели, способные анализировать код и делать его краткие резюме.
Я пробовал использовать Sphinx с расширением AutoAPI, но оно не решает проблему отсутствия комментариев. Основной вопрос заключается в том, существуют ли инструменты автодокументирования, которые могут предоставить описания функций и методов на основе их кода, а не только их сигнатур. Или я что-то упускаю в этом процессе?
<b>Пример исходного кода:</b> <br/>
<pre><code class="python">def get_docs_time_range(docs: list[DTOStatus]) -> tuple[datetime, datetime]:
dates = [doc.created_at_timestamp for doc in docs]
dates.sort()
earliest = dates[0]
latest = dates[-1]
return (earliest, latest)</code></pre>
<b>Желаемый результат:</b> <br/>
<pre><code class="python">def get_docs_time_range(docs: list[DTOStatus]) -> tuple[datetime, datetime]:
"""
Returns the earliest and latest timestamp from the given list of DTOStatus objects.
Args:
docs (list[DTOStatus]): A list of DTOStatus objects containing the timestamps to analyze.
Returns:
tuple[datetime, datetime]: A tuple containing the earliest and latest timestamps from the input list.
"""
dates = [doc.created_at_timestamp for doc in docs]
Документирование кода, особенно в больших проектах, может быть сложной задачей, особенно если в коде отсутствуют комментарии. На данный момент нет идеального решения для генерации полных и точных комментариев только на основе анализа кода, однако можно использовать несколько подходов и инструментов для улучшения процесса документирования. ### Инструменты для автодокументации 1. **Sphinx + AutoAPI**: Хотя вы уже пробовали Sphinx с AutoAPI, стоит учитывать, что они способны создавать документацию на основе аннотаций, типов и структуры кода. Однако, как вы отметили, они не предоставляют описания функций по умолчанию. 2. **Docstring Generation Tools**: - **Docstring Generator**: Это расширение для некоторых редакторов, которое может генерировать заготовки для docstring на основе сигнатуры функции. Например, `pydocstring` (доступен в VS Code) может помочь, но все равно требует ручного взаимодействия. - **pydocstyle**: Этот инструмент проверяет ваши docstrings на соответствие стилевым стандартам. 3. **AI-Driven Tools**: - **OpenAI Codex и другие AI-модели**: Некоторые инструменты на основе ИИ могут анализировать код и генерировать комментарии и описания. Например, GitHub Copilot может создать docstring для функции, опираясь на контекст кода, хотя качество может варьироваться. - **Kite**: Это инструмент для автокомплектации на основе ИИ, который также может предложить улучшения в комментариях. 4. **PyCharm**: Если вы используете PyCharm, он имеет встроенные функции для генерации docstring, которые могут создавать заготовки основанные на сигнатуре функции и типах данных. ### Рекомендуемый процесс документирования 1. **Пересмотрите код**: Начните с изучения наиболее важных функций. Попробуйте понять, что они делают, и создайте предварительные описания. 2. **Используйте инструменты ИИ**: Если у вас есть доступ к инструментам на основе ИИ, таких как OpenAI Codex, вы можете использовать их для автоматической генерации комментариев и описаний. 3. **Применяйте индивидуальный подход**: После генерации комментариев с помощью ИИ, скорректируйте их вручную. Хотя ИИ может помочь, его описания могут не всегда быть точными или достаточно полными. 4. **Стандартизируйте формат docstring**: Следуйте стандартам (например, Google Style, NumPy/SciPy, reStructuredText) для ваших docstrings. Это упрощает процесс и делает документацию более читабельной. 5. **Поэтапная работа**: Покрывайте код документацией постепенно. Сфокусируйтесь на критически важных частях кода и постепенно обрабатывайте остальные. ### Заключение Учитывая, что автоматизированные решения могут не всегда давать идеальный результат, вам, вероятно, потребуется сочетание инструментов и ручного подхода. Наилучшие результаты можно добиться в комбинированном подходе, где мощные инструменты для анализа и генерации текста подсказывают вам, а ваш собственный опыт и знания используются для корректировки и улучшения предложенных описаний.
Топовые ИИ могут это сделать (openai o1/gpt4o, anthropic claude opus/sonet, google gemini pro, qwen 2.5 72b, llama3.2 70b,.. изучи lmsys арену lmarena.ai там можно выбрать домен задачи), у тебя не очень большой объем кода.
Главная ошибка - пытаться одним промптом решить задачу (хотя o1 может быть близок к этому). Поиграй с промптами, твоя задача собрать описание работы твоего кода, опиши все что знаешь сам, напиши запрос, которым можно собрать информацию по функционалу, информацию по структуре кода,.. если есть время, попробуй разобрать код на структурные элементы, хотя бы 3 уровня (например модули - классы - методы) и задавать ИИ один и тот же вопрос, собрав в контексте весь код, структурное описание и в конце задавай вопрос о назначении конкретного элемента, и так повторить для каждого. Собирай ответы в один большой запрос, который уже в последствии можно передать o1 на итоговый анализ (можно и без нее, внутри o1 по уму делает именно это, но так как openai на столько закрытая что готова жестоко наказывать любого, кто попытается узнать этот алгоритм).
Я помню мне хватило одной модели claude sonet и с десяток запросов, чтобы проанализировать исходный код чужого проекта и понять, на сколько ограничен или нет его функционал, при этом я спрашивал у модели итеративно, какой файл исходников ему нужен, в твоем случае все влезет за раз.
Помни что чем больше размер контекстного окна, тем сильнее llm теряет информацию в нем (случайно), но повторение этой информации наоборот увеличивает ее значимость для нее, т.е. исходный код + описание этого кода облегчает для модели анализ. Есть и недостатки, даже топовые модели - переобучены (это болезнь всех нейронок), и какое-нибудь неосторожное ключеове слово или название может заставить модель думать не так как надо а как было написано в обучающих данных, тупой пример - если я хочу написать проект, работающий с api openai, и модель научена на ней, то мне было невероятно сложно заставить модель не генерировать сложный метод формирования api запроса, вместо вызова одной строчки (как я требовал в промпте) curl, прописанной в конфиге... но как только я убрал везде упоминание openai и подробно описал требования, так все прошло на ура. Поэтому, экспериментируй, изучай, перепроверяй все что тебе сгенерирует ИИ. Современный ИИ это не замена, а очень мощный инструмент помощник, который возьмет на себя скучную рутину.
p.s. рекомендую лайфхак
когда тебе нужен короткий ответ на твой вопрос, следуй следующему сценарию (особенно если используешь слабые модели, но работает для нетиповых задач и у топовых), в виде чат-сессии:
{твой вопрос} {добавь текст: 'глубоко вдохни и подумай шаг за шагом'/'take a deep breath and think step by step'} [получи ответ, читать его не обязательно но оставь его в контекстном окне] {задай вопрос: 'а если подумать еще раз'/'but if you think about it again'} [получи еще один ответ, читать его так же не обязательно но оставь его в контекстном окне] {задай окончательный вопрос: 'Итак, какой будет твой ответ?'/'So, what will be your answer?', тут можно определить, в каком виде нужен ответ} [получи окончательный ответ]
По поводу 'take a deep breath' была исследовательская работа, которая показала что эта просьба повышает качество моделей очень значительно, а мои исследования показали что просьба 'подумать еще раз' позволяет модели сомневаться в предыдущем тексте и искать альтернативные варианты, обычно это исправляет ошибки, если это в принципе возможно.
Еще странный совет - попробуй решить задачу на разных языках, не только на английском, сравни ответ, тебя может это удивить.