الوثائق، التمهيدي وتعليقات التعليمات البرمجية

المكاسب:

• القدرة على إنتاج مسودات README وdocstring وسجل التغيير بناءً على الجمهور المستهدف والمصدر باستخدام الذكاء الاصطناعي
• القدرة على فصل طبقات "ماذا/كيف" و"لماذا" في الوثائق وإضافة "لماذا" كإنسان
• التحقق من خطوات التثبيت عن طريق تشغيلها شخصيًا وجعل المستند جزءًا من تغيير الكود

الجزء الأكثر إهمالًا ولكن الأطول عمرًا في البرنامج هو التوثيق. الكود قابل للقراءة حتى بعد مرور أشهر؛ لقد رحل كاتبها، ونُسي السياق، ولم يبقى إلا ما كتب. إن README الجيد (مستند تمهيدي يشرح ماهية المشروع وكيفية تثبيته وتشغيله)، وتعليقات التعليمات البرمجية التوضيحية ووثائق API المحدثة (مرجع يشرح كيفية استخدام الواجهة) يحدد بشكل مباشر سرعة الفريق. يخفف الذكاء الاصطناعي الكثير من "إرهاق الكتابة" من التوثيق - ولكنه يأتي مع فخ: يمكن للذكاء الاصطناعي أن يستنتج من التعليمات البرمجية ما يفعله، لكنه في كثير من الأحيان لا يستطيع معرفة سبب القيام بذلك بهذه الطريقة.

في هذه الوحدة، ستتعلم كيفية إنتاج الملف README، وتعليق التعليمات البرمجية، وسلسلة المستندات (كتلة تعليق مكتوبة لكل وظيفة/فئة)، ووثيقة API وسجل التغيير باستخدام الذكاء الاصطناعي؛ وكيفية الحفاظ إنسانيًا على الجزء الأكثر قيمة من التوثيق: "السبب".

الفرق بين "ماذا" و"لماذا"

هناك طبقتان من الوثائق. الأول هو ماذا/كيف: "تقوم هذه الوظيفة بفرز قائمة"، "تشغيل هذا الأمر للتثبيت". يمكن استخلاصها من الكود والبنية؛ الذكاء الاصطناعي يتفوق هنا. ثانيًا، لماذا: "لماذا جعلنا هذه الخدمة غير متزامنة وليست متزامنة"، "لماذا تبلغ قيمة هذا الحد 30 ثانية"، "لماذا اخترنا هذه المكتبة على الأخرى". هذه ليست مكتوبة في التعليمات البرمجية؛ إنه نتاج قرارات التصميم والقيود وآلام الماضي.

الذكاء الاصطناعي لا يعرف "لماذا"؛ وفي أفضل الأحوال، فهو يشكل تخمينًا معقولًا، وهو أمر خطير، لأن السبب الخاطئ أسوأ من عدم وجود سبب على الإطلاق. لذا فإن تقسيم العمل واضح: يقوم الذكاء الاصطناعي بصياغة "ماذا/كيف"، وتضيف "لماذا". التعليق الأكثر قيمة هو التعليق الذي يوضح ما لا يستطيع الكود قوله.

نصيحة: لا تكرر بتعليق ما يقوله الكود نفسه بوضوح (مثل i = i + 1 // زيادة i بمقدار واحد). يُنتج الذكاء الاصطناعي أحيانًا مثل هذه التعليقات الزائدة عن الحاجة؛ قم بإزالتها وخصص طاقتك لتعليقات "لماذا".

خطوة بخطوة: إنشاء الوثائق باستخدام الذكاء الاصطناعي

1. تحديد الجمهور المستهدف. "مطور بدأ للتو"، "الفريق الخارجي الذي سيستخدم واجهة برمجة التطبيقات هذه"، "أنا المستقبل" - يحدد الجمهور نغمة اللغة والعمق.
2. إعطاء المصدر. قم بإضافة الكود ذي الصلة، وملف README الموجود، ومثال الاستخدام إلى الموجه. الوثيقة غير المصدر هي دعوة للتلفيق.
3. هيكل الفرض. الأقسام القياسية لـ README (الغرض، التثبيت، الاستخدام، التكوين، المساهمة)، تنسيق المشروع لسلسلة المستندات.
4. ضع علامة على مسافات "لماذا". اطلب من الذكاء الاصطناعي تحديد القرارات التي لا يعرف الأساس المنطقي لها على أنها "ملاحظة "لماذا" مطلوبة هنا"؛ ثم تقوم بملء تلك الفراغات.
5. يؤكد. قم بالفعل بتشغيل خطوات التثبيت؛ حاول رمز العينة. الملف التمهيدي الذي لا يعمل هو أسوأ من عدم وجود ملف README على الإطلاق.

ثلاث حالات صغيرة

الحالة 1 - تسريع عملية التمهيد لملف README. كان الملف README الخاص بأداة مفتوحة المصدر مفقودًا؛ واجه المساهمون الجدد صعوبة في التثبيت لمدة ساعتين في المتوسط. أعطى الفريق نصوص التثبيت وpackage.json إلى الذكاء الاصطناعي وقام بصياغة ملف README منظم، ثم قام بتشغيل الخطوات بنفسه على جهاز نظيف وأضاف التبعيتين المفقودتين. انخفض وقت التثبيت للمساهمين اللاحقين إلى متوسط ​​25 دقيقة.

الحالة الثانية - فخ "لماذا" المفتعل. طلب أحد المطورين من الذكاء الاصطناعي التعليق بجوار قيمة المهلة (المهلة = 30). لقد كتب الذكاء الاصطناعي تبريرًا معقولًا ولكنه غير صحيح "للتسامح مع زمن الوصول العالي للشبكة"؛ كان السبب الحقيقي هو الحد التعاقدي للخدمة النهائية وهو 30 ثانية. أدى التفسير الخاطئ إلى قيام مطور لاحق بزيادة القيمة دون داع، مما أدى إلى وقوع حادث. الدرس المستفاد: يجب على صاحب الكود التحقق من التبرير.

الحالة 3 - أصبح معيار Docstring آليًا. الوحدة المساعدة التي تحتوي على 40 وظيفة لا تحتوي على مستندات. تم منح الذكاء الاصطناعي تنسيق المشروع (نمط Google) وأنتج أوصاف المعلمات والإرجاع والاستثناءات لكل وظيفة؛ قام المطور بمراجعة هذه الأمور وإصلاح بعض إعلانات النوع غير الصحيحة. انخفض توثيق 40 وظيفة من حوالي نصف يوم إلى ساعة.

أربعة قوالب قابلة للنسخ

مسودة الملف التمهيدي المنظم:

الجمهور المستهدف: {{على سبيل المثال. مساهم جديد}}. اكتب مسودة التمهيدي بناءً على الملفات أدناه. الأقسام: الغرض، الميزات، المتطلبات، التثبيت، التشغيل، التكوين، الاختبار، المساهمة. استخراج أوامر التثبيت/التشغيل من الملفات الفعلية؛ مناسب. حدد الأماكن التي لست متأكدًا منها باستخدام "[التحقق]". المصدر: {{package.json / البرامج النصية / نموذج التعليمات البرمجية}}

مرجع Docstring/API:

اكتب سلسلة مستندات لهذه الوظائف بتنسيق {{project style: Google/NumPy/JSDoc}}: ملخص قصير، المعلمات (النوع + المعنى)، الإرجاع، طرح الاستثناءات، مثال قصير واحد. لا تكرر ما يقوله الرمز بوضوح. ضع علامة على قرارات التصميم التي تتطلب "لماذا" على أنها "[لماذا ضروري]"، ولا تكتب مبررًا ملفقًا.{{code}}

إزالة المسافات لتعليق "لماذا":

في هذا الكود، قد يسأل المطور التالي "لماذا يحدث هذا؟" (الأرقام السحرية، القرارات غير العادية، الحلول). قم بإعطاء تعليق SKELETON لكل منها، ولكن اترك الأساس المنطقي فارغًا؛ سأقوم بملء التبرير.{{code}}

بيان التغيير/العلاقات العامة:

اكتب {{إدخال سجل التغيير / وصف العلاقات العامة}} من الفرق أدناه. التنسيق: ما الذي تغير (بلغة المستخدم)، لماذا (المشكلة: {{...}})، التغيير الجذري (إن وجد)، هل تم اختباره. اضبط المصطلحات الفنية لتناسب الجمهور المستهدف.{{diff}}

موجه ضعيف / موجه قوي

ضعيف: "اكتب التمهيدي لهذا المشروع."

قوي: "الجمهور المستهدف: مطور يستنسخ هذا الريبو لأول مرة. استنادًا إلى ملف package.json وdocker-compose.yml والمجلدات النصية/، اكتب مسودة README مع أقسام الغرض والمتطلبات والتثبيت والتشغيل والاختبار والمساهمة. استخرج الأوامر من هذه الملفات، ولا تصنعها؛ ضع علامة في أي مكان لست متأكدًا منه باستخدام [التحقق]."

النسخة القوية تعطي الجمهور، والمصدر، والبنية، وقاعدة "اصنعها، ضع علامة عليها"؛ بحيث تكون الوثيقة مبنية على ملفات حقيقية وتكون الأماكن المراد التحقق منها واضحة للعيان.

نوع الوثيقة

الذكاء الاصطناعي يعمل بشكل جيد

يضيف/يتحقق الإنسان

تثبيت التمهيدي

الخطوط العريضة للخطوة

قم بتشغيل الخطوات والتأكيد

دوكسترينغ/API

الهيكل، المعلمة، النوع

النوع الصحيح و "لماذا"

تعليق الكود

ملخص "ماذا يفعل".

"لماذا هذا" مبرر

سجل التغيير/العلاقات العامة

المسودة الأولى

التأثير والدقة

القرار المعماري (ADR)

هيكل عظمي

قرارات وتسويات حقيقية

التوثيق يتطلب الصيانة

أخطر ما في الوثيقة هو عندما تبدو صحيحة رغم أنها كاذبة. عندما يتغير الرمز ولا يتم تحديث المستند، فإنه يضلل القارئ بشكل فعال. الذكاء الاصطناعي يجعل عملية التحديث سهلة: قم بإصدار فرق واسأل "ما هي أجزاء المستند التي يؤثر عليها هذا التغيير؟" قد تسأل. ولكنها العملية التي تضمن التحديث - اجعل تحديث الوثائق جزءًا من تغيير الكود (معيار قبول العلاقات العامة). يتسارع الذكاء الاصطناعي؛ الفريق يبني الانضباط.

تنبيه: لا تنشر دون التحقق من خطوات التثبيت في ملف README. يمكن أن تؤدي وثيقة "العمل المحتمل" إلى إفساد اليوم الأول للمطور الجديد وتقويض الثقة. قم بتنفيذ الخطوات بنفسك في بيئة نظيفة.

الأخطاء الشائعة

• الحصول على "لماذا" ليناسب الذكاء الاصطناعي. التبرير الكاذب أسوأ من عدم وجود تبرير؛ يجب على مالك الكود كتابة سبب التصميم.
• عدم التحقق من خطوات التثبيت. README الذي لا يعمل يدمر الثقة.
• تعليق غير ضروري تكرار الكود. إنه ينتج ضوضاء، ويحجب تفسيرات "السبب" الحقيقية.
• عدم تحديد الجمهور المستهدف. الوثيقة غير الواضحة لمن كتبت لا تفيد المبتدئ ولا الخبير.
• فصل التحديث عن العملية. إذا لم يتم تحديث المستند بالرمز، فإنه سرعان ما يصبح مضللاً.

باختصار

يتخلص الذكاء الاصطناعي من الكثير من العبء الميكانيكي من التوثيق: المسودات السريعة README، وسلسلة الوثائق، ومرجع واجهة برمجة التطبيقات، وسجل التغيير، وأوصاف العلاقات العامة. لكنها لا تستطيع معرفة "السبب"، وهي الطبقة الأكثر قيمة، ومن الخطر اختلاقها. إن تقسيم العمل واضح: الذكاء الاصطناعي ينتج "ماذا/كيف"، وتضيف "لماذا". حدد الجمهور، وقم بتوفير الموارد، وفرض البنية، وتحديد الأماكن المناسبة، والتحقق من كل خطوة تثبيت عن طريق تشغيلها بنفسك. اجعل التوثيق جزءًا لا يتجزأ من تغيير الكود.

مهمة التطبيق

اختر وحدة نمطية أو مشروعًا صغيرًا وثائقه مفقودة أو قديمة. قم أولاً بإنشاء مخطط تفصيلي من الذكاء الاصطناعي باستخدام قالب "مسودة README المنظمة" (أو سلسلة الوثائق)؛ تأكد من إعطاء المصدر والجمهور المستهدف. ثم انتقل إلى كل نقطة حدد فيها الذكاء الاصطناعي علامة [تحقق] أو [لماذا تحتاج]: قم فعليًا بتشغيل خطوات الإعداد واملأ التصميم "لماذا" بمعرفتك الخاصة. لاحظ عدد الخطوات التي تحتاج إلى إصلاح وعدد "الأسباب" التي أضفتها.

قائمة مرجعية

• [ ] في الوثائق، أميز بين طبقتي "ماذا/كيف" و"لماذا".
• [ ] لا أجعل الذكاء الاصطناعي يخترع "السبب"، بل أضيفه بنفسي.
• [ ] أعطي الموجه للجمهور المستهدف والملفات المصدر الفعلية.
• [ ] أتحقق من نقاط [التحقق] التي حددها الذكاء الاصطناعي من خلال تنفيذها شخصيًا.
• [ ] أقوم بإزالة التعليقات غير الضرورية التي تكرر الكود.
• [ ] أقوم بإجراء جزء من تحديث الوثائق ضمن تغيير الكود.