اسناد، README و نظرات کد

سود:

• امکان تولید پیش‌نویس‌های README، docstring و تغییرات بر اساس مخاطبان هدف و منبع با هوش مصنوعی
• امکان جداسازی لایه‌های «چگونه» و «چرا» در مستندات و افزودن «چرا» به عنوان یک انسان
• بررسی مراحل نصب با اجرای شخصی آنها و تبدیل سند به بخشی از تغییر کد

اغلب نادیده گرفته شده اما طولانی ترین بخش نرم افزار مستندسازی است. کد حتی پس از ماه ها قابل خواندن است. کسی که آن را نوشته رفته است، زمینه فراموش می شود و تنها چیزی که نوشته شده باقی می ماند. یک README خوب (سند مقدماتی که توضیح می‌دهد یک پروژه چیست و چگونه آن را نصب و اجرا کنید)، نظرات کد توضیحی و اسناد API به‌روز (مرجعی که نحوه استفاده از یک رابط را توضیح می‌دهد) مستقیماً سرعت یک تیم را تعیین می‌کند. هوش مصنوعی بسیاری از «خستگی نوشتن» را از مستندات خارج می‌کند – اما با یک تله همراه است: هوش مصنوعی می‌تواند از روی کد استنباط کند که چه کاری انجام می‌دهد، اما اغلب نمی‌داند چرا این کار به این صورت انجام می‌شود.

در این واحد، نحوه تولید README، کامنت کد، رشته docstring (بلاک نظر نوشته شده در هر تابع/کلاس)، سند API و تغییرات را با هوش مصنوعی یاد خواهید گرفت. و چگونه می توان ارزشمندترین بخش اسناد را به صورت انسانی حفظ کرد: «چرا».

تمایز بین "چی" و "چرا"

دو لایه اسناد وجود دارد. اولین مورد این است که چه/چگونه: "این تابع یک لیست را مرتب می کند"، "این دستور را برای نصب اجرا کنید". اینها را می توان از کد و ساختار استخراج کرد. هوش مصنوعی در اینجا برتری دارد. دوم، چرا: "چرا این سرویس را به جای همزمان ناهمزمان کردیم"، "چرا این مقدار محدود 30 ثانیه است"، "چرا این کتابخانه را بر دیگری انتخاب کردیم". اینها در کد نوشته نشده اند. این محصول تصمیمات طراحی، محدودیت ها و درد گذشته است.

هوش مصنوعی "چرا" را نمی داند. در بهترین حالت، یک حدس معقول می‌سازد که خطرناک است، زیرا دلیل اشتباه از بی‌دلیلی بدتر است. بنابراین تقسیم کار واضح است: هوش مصنوعی «چی/چگونه» را پیش‌نویس می‌کند، شما «چرا» را اضافه می‌کنید. با ارزش ترین نظر آن چیزی است که چیزی را که کد نمی تواند بگوید را می گوید.

نکته: آنچه را که خود کد به وضوح می گوید را با یک نظر تکرار نکنید (مانند i = i + 1 // افزایش i توسط یک). AI گاهی اوقات چنین نظرات اضافی را تولید می کند. آنها را حذف کنید و انرژی خود را صرف نظرات "چرا" کنید.

گام به گام: تولید اسناد با هوش مصنوعی

1. مخاطب هدف را مشخص کنید. «توسعه‌دهنده‌ای که تازه شروع به کار می‌کند»، «تیم خارجی که از این API استفاده می‌کند»، «من آینده» - مخاطب لحن زبان و عمق را تعیین می‌کند.
2. منبع رو بفرمایید کد مربوطه، README موجود، استفاده از نمونه را به دستور اضافه کنید. سند بدون منبع، دعوت به ساخت است.
3. ساختار تحمیلی بخش های استاندارد برای README (هدف، نصب، استفاده، پیکربندی، مشارکت)، قالب پروژه برای رشته مستند.
4. فضاهای «چرا» را علامت بزنید. از هوش مصنوعی بخواهید تصمیماتی را که منطق آنها را نمی داند به عنوان "یادداشت "چرا" در اینجا لازم است" علامت گذاری کند. سپس آن جاهای خالی را پر می کنید.
5. تأیید کنید. در واقع مراحل نصب را اجرا کنید. کد نمونه را امتحان کنید README که کار نمی کند بدتر از عدم خواندن README است.

سه کیف کوچک

مورد 1 - README ورود را تسریع کرد. README یک ابزار منبع باز وجود نداشت. مشارکت کنندگان جدید به طور متوسط ​​2 ساعت با نصب مشکل داشتند. تیم اسکریپت‌های نصب و package.json را به هوش مصنوعی داد و یک README ساختاریافته تهیه کرد، سپس مراحل را خودشان روی یک ماشین تمیز اجرا کردند و دو وابستگی گمشده را اضافه کردند. زمان نصب برای مشارکت کنندگان بعدی به طور متوسط ​​به 25 دقیقه کاهش یافت.

مورد 2 - تله "چرا" ساخته شده. توسعه‌دهنده‌ای از هوش مصنوعی درخواست یک نظر در کنار یک مقدار مهلت زمانی (timeout=30) کرد. هوش مصنوعی یک توجیه منطقی اما نادرست نوشت: «برای تحمل تأخیر بالای شبکه»؛ دلیل واقعی محدودیت 30 ثانیه ای قراردادی یک سرویس پایین دستی بود. این تفسیر نادرست باعث شد که یک توسعه‌دهنده بعدی ارزش را به طور غیرضروری افزایش دهد و منجر به یک حادثه شود. درس: صاحب کد باید توجیه را تأیید کند.

مورد 3 - استاندارد Docstring خودکار شده است. یک ماژول کمکی با 40 عملکرد هیچ رشته مستندسازی نداشت. به هوش مصنوعی قالب پروژه (سبک گوگل) داده شد و توضیحات پارامتر، بازگشت و استثنا برای هر تابع تولید شد. توسعه‌دهنده این موارد را بررسی کرده و چند اعلان نوع نادرست را اصلاح کرده است. مستندسازی 40 عملکرد از حدود نیم روز به یک ساعت کاهش یافت.

چهار قالب قابل کپی

پیش نویس ساختار یافته README:

مخاطبان هدف: {{به عنوان مثال مشارکت‌کننده جدید}}. یک پیش‌نویس README بر اساس فایل‌های زیر بنویسید. بخش ها: هدف، ویژگی ها، الزامات، نصب، عملیات، پیکربندی، آزمایش، مشارکت. استخراج دستورات نصب/اجرا از فایل های واقعی. اتصالات. مکان‌هایی را که مطمئن نیستید با «[VERIFY]» علامت‌گذاری کنید. منبع: {{package.json / اسکریپت / کد نمونه}}

مرجع Docstring/API:

برای این توابع رشته مستند را در قالب {{طرح پروژه: Google/NumPy/JSDoc}} بنویسید: خلاصه کوتاه، پارامترها (نوع + معنی)، بازگشت، استثناهای پرتاب شده، 1 مثال کوتاه. آنچه را که کد به وضوح می گوید تکرار نکنید. تصمیمات طراحی که نیاز به "چرا" را به عنوان "[چرا ضروری]" علامت گذاری کنید، یک توجیه ساختگی ننویسید.{{کد}}

فاصله های نظر "چرا" را حذف کنید:

در این کد، توسعه دهنده بعدی ممکن است بپرسد "چرا اینطور است؟" (اعداد جادویی، تصمیمات غیر معمول، راه حل ها). برای هر کدام یک نظر بدهید، اما منطق را خالی بگذارید. من توجیه را تکمیل می کنم.{{کد}}

بیانیه تغییرات/PR:

یک {{ مدخل تغییرات / توضیحات روابط عمومی }} از تفاوت زیر بنویسید. قالب: چه چیزی تغییر کرد (به زبان کاربر)، چرا (مسئله: {{...}})، تغییر شکسته (در صورت وجود)، آیا آزمایش شده است. اصطلاحات فنی را برای مخاطب هدف تنظیم کنید.{{تفاوت}}

اعلان ضعیف / اعلان قوی

ضعیف: "یک README برای این پروژه بنویسید."

قوی: "مخاطبان هدف: توسعه دهنده ای که این مخزن را برای اولین بار شبیه سازی می کند. بر اساس بسته.json، docker-compose.yml و scripts/ پوشه پیوست شده، یک پیش نویس README با بخش های Purpose, Requirements, Installation, Operation, Testing, Contribution بنویسید. دستورات را از این مخزن استخراج کنید.

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

نوع سند

هوش مصنوعی خوب عمل می کند

انسان اضافه/تأیید می کند

نصب README

طرح کلی مرحله

مراحل را اجرا کرده و تایید کنید

Docstring/API

ساختار، پارامتر، نوع

نوع صحیح و "چرا"

نظر کد

خلاصه "آنچه دارد انجام می دهد".

توجیه "چرا این است".

تغییرات/PR

پیش نویس اول

تاثیر و دقت

تصمیم گیری معماری (ADR)

اسکلت

تصمیمات واقعی و مصالحه

اسناد نیاز به تعمیر و نگهداری دارند

خطرناک ترین جنبه یک سند زمانی است که درست به نظر برسد حتی اگر نادرست باشد. هنگامی که کد تغییر می کند و سند به روز نمی شود، خواننده را به طور فعال گمراه می کند. هوش مصنوعی به روز رسانی را آسان می کند: یک تفاوت ایجاد کنید و بپرسید "این تغییر بر کدام بخش های سند تأثیر می گذارد؟" ممکن است بپرسید اما این فرآیند است که به روز بودن را تضمین می کند - به روز رسانی اسناد را بخشی از تغییر کد کنید (معیار پذیرش PR). هوش مصنوعی شتاب می گیرد؛ تیم نظم و انضباط ایجاد می کند.

احتیاط: بدون تأیید مراحل نصب در README منتشر نکنید. یک سند "احتمالا کار" می تواند روز اول یک توسعه دهنده جدید را خراب کند و اعتماد را از بین ببرد. مراحل را خودتان در محیطی تمیز اجرا کنید.

اشتباهات رایج

• دریافت «چرا» متناسب با هوش مصنوعی. توجیه نادرست بدتر از عدم توجیه است. صاحب کد باید دلیل طراحی را بنویسد.
• عدم تایید مراحل نصب README که کار نمی کند اعتماد را از بین می برد.
• نظر غیر ضروری تکرار کد. نویز تولید می کند و تعابیر واقعی «چرا» را پنهان می کند.
• عدم مشخص کردن مخاطب هدف سندی که مشخص نیست برای چه کسی نوشته شده است، نه برای تازه کار و نه برای کارشناس فایده ای ندارد.
• جداسازی آپدیت از فرآیند اگر سند با کد به روز نشود، به سرعت گمراه کننده می شود.

به طور خلاصه

هوش مصنوعی بسیاری از بار مکانیکی را از اسناد خارج می کند: پیش نویس های سریع README، docstring، مرجع API، تغییرات و توضیحات روابط عمومی. اما نمی تواند «چرا» را که ارزشمندترین لایه است، بداند و ساختن آن خطرناک است. تقسیم کار واضح است: هوش مصنوعی «چی/چگونه» را تولید می‌کند، شما «چرا» را اضافه می‌کنید. مخاطب را مشخص کنید، منابع را تهیه کنید، ساختاری را تحمیل کنید، مکان‌هایی را که مناسب هستند علامت‌گذاری کنید و هر مرحله نصب را با اجرای خودتان تأیید کنید. اسناد را به بخشی جدایی ناپذیر از تغییر کد تبدیل کنید.

وظیفه کاربردی

ماژول یا پروژه کوچکی را انتخاب کنید که مستندات آن گم شده یا قدیمی است. ابتدا یک طرح کلی از هوش مصنوعی با الگوی "پیش نویس ساختار یافته README" (یا رشته مستند) ایجاد کنید. مطمئن شوید که منبع و مخاطب هدف را ذکر کنید. سپس از هر نقطه‌ای که هوش مصنوعی [VERIFY] یا [WHY NEEDED] را علامت‌گذاری کرده است عبور کنید: در واقع مراحل راه‌اندازی را اجرا کنید و طرح «چرایی» را با دانش خود پر کنید. توجه داشته باشید که چند مرحله باید اصلاح شود و چند "چرا" اضافه کرده اید.

چک لیست

• [ ] در مستندات، لایه‌های «چی/چگونه» و «چرا» را تشخیص می‌دهم.
• [ ] من هوش مصنوعی "چرا" را تشکیل نمی دهم، خودم آن را اضافه می کنم.
• [ ] من به درخواست مخاطبان هدف و فایل های منبع واقعی می دهم.
• [ ] من نقاط [VERIFY] مشخص شده توسط هوش مصنوعی را با اجرای شخصی آنها تأیید می کنم.
• [ ] نظرات غیر ضروری که کد را تکرار می کنند حذف می کنم.
• [ ] من به روز رسانی اسناد را بخشی از تغییر کد می کنم.