مستندسازی کد با هوش مصنوعی؛ README و راهنما

مستندسازی کد با هوش مصنوعی باید از فایل‌های واقعی پروژه و فرمان‌های قابل بررسی شروع شود. مدل می‌تواند README، راهنمای اجرا و توضیح ورودی و خروجی را مرتب کند، اما نباید دستور نصب یا قابلیت ناموجود بسازد. این راهنما برای یک ابزار CSV فرضی، ساختار مستندات و روش کنترل هر ادعا را نشان می‌دهد.

README خوب به چه پرسش‌هایی پاسخ می‌دهد؟#

خواننده تازه باید بفهمد پروژه چه کاری انجام می‌دهد، چه پیش‌نیازی دارد، چگونه اجرا می‌شود و خروجی مورد انتظار چیست. اگر سند فقط نام فناوری‌ها را فهرست کند، مسیر شروع روشن نیست. اگر فرمان اجرا غلط باشد، توضیحات طولانی نیز کاربر را به نتیجه نمی‌رسانند.

راهنمای README در GitHub نقش این فایل در معرفی و شروع استفاده از پروژه را توضیح می‌دهد. ساختار نمونه این مقاله یک پیشنهاد آموزشی مستقل است. سند پروژه شما باید با نوع مخاطب و روش واقعی اجرا هماهنگ باشد.

به مدل چه فایل‌هایی بدهیم؟#

فایل ورودی برنامه، تعریف وابستگی‌ها، نمونه تنظیمات بدون راز و یک داده آزمایشی کوچک را ارائه کنید. برای پروژه بزرگ، بخش مورد نیاز را محدود کنید. مدل بدون دیدن فرمان‌های موجود نباید روش نصب یا انتشار را حدس بزند. اگر اطلاعات کافی نیست، خروجی باید سؤال یا بخش نیازمند تأیید داشته باشد.

کلید API، رمز، فایل خصوصی و داده کاربر را وارد سند یا پرامپت نکنید. نمونه تنظیمات باید نام متغیر و مقدار نمایشی بی‌خطر داشته باشد. دستورهایی که داده را حذف یا سامانه را تغییر می‌دهند باید در زمینه و با هدف روشن مستند شوند؛ آن‌ها را به مسیر شروع ساده اضافه نکنید.

پروژه آموزشی ابزار CSV#

فرض کنید یک ابزار کوچک به نام csv-check داریم که از فایل ورودی، تعداد ردیف و فهرست شناسه‌های تکراری را گزارش می‌کند. این پروژه فرضی است و فرمان زیر قرارداد نمونه است، نه دستور اجرای مخزن فعلی سایت. ورودی شامل ستون id است و خروجی یک گزارش JSON دارد.

csv-check/
  check_csv.py
  examples/sample.csv
  README.md

فرمان آموزشی پس از تطبیق با کد واقعی چنین مستند می‌شود:

python check_csv.py --input examples/sample.csv --output report.json

اگر برنامه واقعی آرگومان output ندارد، مدل باید فرمان را اصلاح کند، نه اینکه قابلیت تازه را در README وعده دهد. مستندات رفتار موجود را توضیح می‌دهند؛ پیشنهاد قابلیت آینده باید در بخش جدا و با وضعیت پیشنهادی بماند.

قالب پیشنهادی README#

معرفی و محدوده#

در دو جمله بگویید ابزار چه مسئله‌ای را حل می‌کند و چه کاری خارج از محدوده است. برای مثال، شمارش شناسه تکراری با پاکسازی یا حذف ردیف فرق دارد. اگر خروجی فقط گزارش است، کاربر نباید انتظار تغییر خودکار فایل را داشته باشد.

شروع سریع#

پیش‌نیاز، دریافت پروژه، نصب لازم و یک اجرای نمونه را به ترتیب بیاورید. فرمان‌ها را در محیط مناسب اجرا کنید و خروجی قابل انتظار را نشان دهید. اگر بخشی به سرویس خارجی وابسته است، نوع وابستگی را توضیح دهید و مقدار واقعی راز را در مثال نگذارید.

ورودی و خروجی#

نام ستون، قالب، رمزگذاری و قواعد مقدار خالی را بنویسید. برای خروجی، یک نمونه کوچک با توضیح فیلدها ارائه کنید. نمونه باید از ورودی آموزشی قابل محاسبه باشد. عددی که در مثال خروجی نوشته شده باید با همان داده هماهنگ باشد.

خطاها و راه‌حل‌ها#

خطای نبود فایل، ستون ناقص و داده نامعتبر را جدا کنید. برای هرکدام نشانه، علت احتمالی و اقدام بررسی را بنویسید. توصیه عمومی «دوباره نصب کنید» برای همه خطاها مناسب نیست. اگر راه‌حل قطعی ندارید، مسیر تشخیص را توضیح دهید.

پرامپت آماده مستندسازی کد#

فایل‌های پروژه و نمونه اجرا را در ادامه می‌دهم. README برای کاربر تازه بنویس. هر فرمان، وابستگی و قابلیت باید از فایل ورودی شاهد داشته باشد. نام آرگومان یا خروجی جدید نساز. بخش‌های معرفی، پیش‌نیاز، شروع سریع، قرارداد ورودی و خروجی، خطاهای رایج و محدودیت را بیاور. پیشنهادهای توسعه را از رفتار موجود جدا کن. برای هر ادعای نیازمند اجرا، یک مورد تأیید در گزارش داخلی بنویس. راز و مقدار واقعی متغیر خصوصی را منتشر نکن.

برای توضیح تابع، ورودی، خروجی، خطا و اثر جانبی را بخواهید. بازگویی خط‌به‌خط کد معمولاً مستندات کاربردی نمی‌سازد. خواننده بیشتر نیاز دارد بداند تابع چه قراردادی دارد و چه فرضی را رعایت می‌کند. مثال تابع باید همان رفتار را نشان دهد.

چگونه سند را راستی‌آزمایی کنیم؟#

مسیر شروع را از محیط مناسب و بدون تکیه بر تنظیمات پنهان خودتان دنبال کنید. فرمان‌ها باید با فایل‌های موجود و نسخه‌های اعلام‌شده سازگار باشند. لینک‌های نسبی، نام فایل و حروف بزرگ و کوچک را بررسی کنید؛ اختلاف کوچک روی بعضی سامانه‌ها لینک را می‌شکند.

نمونه خروجی را با اجرای واقعی مقایسه کنید. اگر اجرا در دسترس نیست، آن بخش را پیشنهادی و نیازمند تأیید نگه دارید. نوشتن «تست شد» بدون شاهد، اعتماد به مستند را کاهش می‌دهد. برای API نیز نمونه درخواست باید با مسیر و قرارداد واقعی هماهنگ باشد، نه طرحی که مدل حدس زده است.

نگهداری مستندات همراه تغییر کد#

وقتی آرگومان، خروجی یا روش نصب تغییر می‌کند، بخش مرتبط سند را در همان تغییر بازبینی کنید. از AI بخواهید اختلاف کد را با README مقایسه و بخش‌های احتمالاً قدیمی را پیدا کند. تصمیم نهایی باید از رفتار جدید و نتیجه اجرا بیاید. تاریخ تازه بدون اصلاح محتوای قدیمی ارزش اضافه نمی‌کند.

برای تشخیص مشکل اجرا، رفع خطای پایتون، برای قرارداد محصول، نوشتن PRD و برای طراحی بررسی، تست کیس مکمل‌اند. در GPT Plus می‌توانید نمونه کد عمومی را به پیش‌نویس سند تبدیل کنید و فرمان‌های نهایی را در محیط پروژه تأیید کنید.