لقد غيرت الذكاء الاصطناعي ما يجب على المهندسين توثيقه بأنفسهم. يمكن لـ GitHub Copilot و Cursor و Mintlify إنشاء وثائق أولية: أوصاف المعلمات، وملخصات الوظائف، وهياكل README. ما لا يمكنهم كتابته هو طبقة النية: القرار الذي تم اتخاذه، والمقايضة التي تم قبولها، والقيود التي كانت مهمة، والخيار الذي رفضه الفريق.
يُظهر الكود السلوك. ونادراً ما يحفظ الأساس المنطقي. وعادةً ما يوجد هذا الأساس المنطقي في سلسلة محادثات على Slack، أو تعليق على تذكرة، أو مراجعة لحادث، أو في ذاكرة شخص ما.
أظهر استطلاع المطورين لعام 2024 الذي أجرته Stack Overflow أن 61% من المطورين المحترفين يقضون أكثر من 30 دقيقة يوميًا في البحث عن إجابات أثناء العمل، ويقضي واحد من كل أربعة منهم أكثر من ساعة. وبالطبع، لا مفر من بعض عمليات البحث. لكن الهدر الحقيقي هو سياق السبرينت الذي لم يتم تضمينه في الوثيقة أبدًا.
يوضح هذا الدليل ما يجب على المهندسين كتابته بأنفسهم، والأماكن التي يمكن أن تساعد فيها الذكاء الاصطناعي، وكيفية الحفاظ على فائدة وثائق الكود بعد انتهاء السبرينت.
TL;DR
يمكن للذكاء الاصطناعي صياغة الطبقة الميكانيكية من التوثيق: سلاسل الوثائق، وأنواع المعلمات، وملخصات الوظائف، وهياكل ملفات README. ولا يزال يتعين على المهندسين كتابة طبقة النوايا: القرارات، والمفاضلات، والقيود، والخيارات المرفوضة الكامنة وراء الكود.
يجب على المهندسين الاستمرار في كتابة ذلك بأنفسهم، في سجلات قرارات الهندسة المعمارية، وأوصاف طلبات السحب (PR)، والتعليقات التوضيحية المرفقة مع الكود. تمنع طبقة النوايا المطور التالي من إجراء هندسة عكسية للقرارات من أسماء المتغيرات، ورسائل الالتزام، وطلبات السحب القديمة. يمكن للذكاء الاصطناعي الآن صياغة الأجزاء الروتينية: أنواع المعلمات، وأوصاف الإرجاع، وملخصات الوظائف الأساسية.
ما الذي يجب أن تشرحه وثائق الكود فعليًا؟
يجب أن تساعد وثائق الكود المطور التالي على فهم وظيفة الكود، وكيفية استخدامه بأمان، ولماذا تم بناؤه بهذه الطريقة. وتظهر هذه الوثائق في مكانين: داخل ملفات المصدر كتعليقات وسلاسل نصية توضيحية، وخارج ملفات المصدر كملفات README، ومراجع واجهة برمجة التطبيقات (API)، ودفاتر التشغيل، وملاحظات الهندسة.
تصبح معظم قواعد الكود صعبة القراءة بعد اختفاء سياق القرار. ربما يكون المطور الأصلي قد قام بموازنة ذكية. لكن المطور التالي لا يرى سوى النتيجة النهائية، وليس المنطق وراءها.
والنتيجة: يقوم كل عضو جديد في الفريق بعملية هندسة عكسية للنوايا انطلاقًا من أسماء المتغيرات ورسائل الالتزام وطلبات السحب القديمة. وهذا يؤدي إلى إبطاء عملية انضمام الموظفين الجدد والمراجعات وتصحيح الأخطاء والتغييرات المستقبلية في نفس المجال.
تجيب الوثائق الجيدة على أربعة أسئلة:
- لمن مخصص هذا الكود؟ المطورون الداخليون، المساهمون في البرمجيات مفتوحة المصدر، مستخدمو واجهة برمجة التطبيقات (API) الخارجيون، أم المستخدمون النهائيون
- ما المشكلة التي يحلها؟ الحاجة التجارية أو التقنية الكامنة وراء الوحدة النمطية
- لماذا تم اختيار هذا النهج؟ البدائل التي تم النظر فيها والمفاضلات التي تم قبولها
- أين توجد الأجزاء ذات الصلة؟ الوحدات التابعة، والخدمات الأولية، وقرارات البنية، والتذاكر، ودفاتر التشغيل
إن السؤال "لماذا" هو الذي يستحق أكبر قدر من الاهتمام البشري.
يعد البحث بالفعل عبئًا كبيرًا على العمل المعرفي خارج مجال الهندسة أيضًا. أظهر استطلاع إدارة المعرفة الذي أجرته ClickUp أن 57% من الموظفين يضيعون الوقت في البحث عن المعلومات المتعلقة بالعمل في المستندات الداخلية أو قواعد المعرفة. وعندما لا يتمكنون من العثور على ما يحتاجون إليه، يلجأ 1 من كل 6 إلى حلول بديلة شخصية: البحث في رسائل البريد الإلكتروني القديمة أو الملاحظات أو لقطات الشاشة.
تتعطل وثائق الكود بنفس الطريقة: إذا لم يتمكن المطورون من العثور على التفسير، فهذا يعني أن التفسير غير موجود.
فثمن الخطأ باهظ. وصف أحد المعلقين على r/AskProgramming سير عمل RPA حيث كاد زر غير موثق أن يؤدي إلى فرض رسوم مصرفية آلية وإرسال رسائل للعملاء.
يعد البحث بالفعل عبئًا كبيرًا على العمل المعرفي خارج مجال الهندسة أيضًا. أظهر استطلاع إدارة المعرفة الذي أجرته ClickUp أن 57% من الموظفين يضيعون الوقت في البحث عن المعلومات المتعلقة بالعمل في المستندات الداخلية أو قواعد المعرفة. وعندما لا يتمكنون من العثور على ما يحتاجون إليه، يلجأ 1 من كل 6 إلى حلول بديلة شخصية: البحث في رسائل البريد الإلكتروني القديمة أو الملاحظات أو لقطات الشاشة.
تتعطل وثائق الكود بنفس الطريقة: إذا لم يتمكن المطورون من العثور على التفسير، فهذا يعني أن التفسير غير موجود.
فثمن الخطأ باهظ. وصف أحد المعلقين على r/AskProgramming سير عمل RPA حيث كاد زر غير موثق أن يؤدي إلى فرض رسوم مصرفية آلية وإرسال رسائل للعملاء.
ما هي الأنواع الرئيسية لتوثيق الكود؟
الأنواع الخمسة الرئيسية هي التعليقات المضمنة، وسلاسل الوثائق، وملفات README، والويكي الداخلية، ووثائق واجهة برمجة التطبيقات الخارجية. كل منها يخدم قارئًا مختلفًا في لحظة مختلفة. وخلطها يجعل الوثائق أصعب في الكتابة والاستخدام. ملف README الذي يقرأ كسلسلة وثائق يفقد المساهمين الجدد. وسلسلة الوثائق التي تقرأ كصفحة ويكي تصبح عبئًا زائدًا داخل ملفات المصدر.
التعليقات المضمنة وسلاسل التوثيق
يجب أن تشرح التعليقات المضمنة في النص الأسباب غير الواضحة. فالتعليق الذي يعيد صياغة x = x + 1 على أنه "زيادة x" لا يضيف شيئًا. أما التعليق الذي يقول "تعويض لاستجابة واجهة برمجة التطبيقات ذات الفهرس صفر" فيستحق وجوده لأن الكود لا يمكنه إظهار هذا القيد الخارجي. احتفظ بالتعليقات المضمنة في النص للمنطق غير الواضح داخل نص الدالة.
Docstrings هي أوصاف منظمة مرفقة بالوظائف أو الفئات أو الوحدات النمطية. وهي تغطي المعلمات وقيم الإرجاع والاستثناءات وأمثلة الاستخدام. لكل لغة قواعدها الخاصة. اتبع القواعد التي تتوقعها لغتك بالفعل: PEP 257 لـ Python docstrings، وJavadoc لـ Java، وJSDoc لـ JavaScript وTypeScript.
قارن بين هذين المثالين:
سلسلة توثيق ضعيفة:
سلسلة توثيق قوية:
يحدد الثاني الوظيفة بوضوح، ويوثق معلماتها، ويبرز افتراضًا: يستخدم مسار الدفع معدل ضريبة بنسبة 8.25%.
ملفات README، ومواقع الويكي، والوثائق الخارجية
يجب أن تجيب ملف README على خمسة أسئلة بالترتيب: ما الذي يفعله هذا المشروع؟ كيف أقوم بتثبيته؟ كيف أستخدمه؟ كيف أساهم فيه؟ أين أحصل على المساعدة؟ إذا لم يتمكن المساهم الجديد من العثور على مسار الإعداد بسرعة، فهذا يعني أن ملف README إما أنه مكتظ بالمعلومات أو أنه غير منظم بشكل جيد.
تعد مواقع الويكي وقواعد المعرفة هي الأفضل للمحتوى الذي يمتد عبر مستودعات أو خدمات متعددة: قرارات الهندسة المعمارية، وأدلة التمهيد، ودفاتر التشغيل. إن موقع ويكي لا يرتبط به أحد من الكود يصبح مشكلة بحث ثانية.
تغطي الوثائق الخارجية مراجع واجهة برمجة التطبيقات (API) وأدلة حزمة أدوات التطوير (SDK) والوثائق الموجهة للمستخدمين. وهي تخدم مستخدمي الكود الخاص بك، وليس المساهمين فيه. تحتاج الوثائق الخارجية إلى مزيد من التفاصيل حول الإعداد، وخطوات مصادقة أوضح، وهيكل على غرار المراجع، لأن القارئ قد لا يكون على دراية بقاعدة الكود الخاصة بك على الإطلاق.
إذا لم يكن لدى الفريق هيكل بعد، فابدأ بنموذج توثيق تقني للهندسة وملاحظات الإعداد، أو نموذج توثيق مشروع للأهداف والمسؤولين والمعالم والقرارات. قم بتكييف الأقسام بدلاً من ابتكار تنسيق من الصفر.
| النوع | الجمهور المستهدف | تواتر التحديث | الموقع النموذجي |
|---|---|---|---|
| التعليقات المضمنة | المطورون الذين يقرؤون مسار كود معين | عندما يتغير سلوك الكود | ملفات المصدر |
| سلاسل الوثائق | المطورون الذين يستدعون دالة أو فئة أو وحدة نمطية | عندما تتغير الواجهة | ملفات المصدر |
| README | المساهمون والمقيّمون الجدد | لكل إصدار رئيسي أو تغيير في المشروع | جذر المستودع |
| ويكي أو قاعدة المعرفة | الفرق الداخلية وأصحاب المصلحة عبر الفرق | مع تغير القرارات أو العمليات | ويكي المستودع أو قاعدة المعرفة المشتركة |
| وثائق واجهة برمجة التطبيقات الخارجية | مستخدمو واجهة برمجة التطبيقات والمستخدمون النهائيون | حسب الإصدار أو إصدار واجهة برمجة التطبيقات (API) | منصة التوثيق |
كيف تكتب الوثائق فعليًا اليوم؟
استخدم الذكاء الاصطناعي للأجزاء التي يمكنه صياغتها. وخصص وقت الموظفين لاتخاذ القرارات، والتعامل مع القيود، وإجراء المقايضات.
يمكن للذكاء الاصطناعي الآن صياغة جزء كبير من العمل الميكانيكي: أنواع المعلمات، وأوصاف القيم المرجعة، وملخصات الوظائف الأساسية. ينقسم عمل التوثيق البشري إلى فئتين.
اكتب أولاً كودًا ذاتي التوثيق
أفضل توثيق هو الكود الذي لا يحتاج إلى توثيق تقريبًا. فالأسماء الوصفية، والوظائف ذات الغرض الواحد، والاتفاقيات المتسقة تقلل من عبء التوثيق قبل أن تكتب تعليقًا واحدًا.
تسهل الشفرات ذاتية التوثيق قراءة السلوك. لكنها نادرًا ما تشرح الأسباب الكامنة وراء هذا السلوك. تساعد الأسماء المطورين على تحديد وظيفة كل عنصر. يجب أن تشرح الوثائق الأسباب التي لا يمكن أن تنقلها الأسماء.
قبل إضافة تعليق، اسأل نفسك ما إذا كان تغيير اسم متغير أو استخراج دالة سيجعل التعليق غير ضروري. إذا كانت الإجابة بنعم، فقم بإعادة الهيكلة أولاً. فالاسم الواضح يلغي الحاجة إلى التعليقات التي لا تفعل سوى تفسير التسمية السيئة.
قبل:
بعد:
تنقل النسخة المعاد هيكلتها نفس المعلومات من خلال التسمية وحدها. التعليق الوحيد المفيد الآن هو الذي يشرح سبب استبعاد أدوار معينة، وهو قرار سياسي لا يمكن للكود التعبير عنه بمفرده.
اكتب طبقة النوايا (الجزء الذي لا يستطيع الذكاء الاصطناعي كتابته)
يظهر التنفيذ في الكود. أما النية فتختفي ما لم يكتبها أحد. ونادراً ما يحفظ الكود سبب إجراء المقايضة، أو القيد الذي دفع التصميم، أو البديل الذي تم رفضه.
هناك قاعدة شائعة بين المطورين تلخص هذا الأمر جيدًا: قم بتوثيق "السبب"، وليس "الشيء". تعليق حصل على أعلى عدد من الأصوات على r/coding:
أستطيع أن أرى أن هذا الشرط يؤدي إلى تفرع بين المستخدمين الأحمر والأزرق. أخبرني لماذا يتم تصنيف المستخدمين بهذه الطريقة ولماذا نقوم بالتفرع بينهم.
أستطيع أن أرى أن هذا الشرط يؤدي إلى تفرع بين المستخدمين الأحمر والأزرق. أخبرني لماذا يتم تصنيف المستخدمين بهذه الطريقة ولماذا نقوم بالتفرع بينهم.
قد تساعد رسالة الالتزام أثناء المراجعة، لكنها مكان غير مناسب على المدى الطويل لتبرير التصميم لأن القراء في المستقبل نادرًا ما يجدونها في اللحظة التي يحتاجون إليها.
كتب ويل لارسون، الرئيس التنفيذي السابق للتكنولوجيا في Calm ومؤلف كتاب An Elegant Puzzle، عن قيمة سجلات قرارات الهندسة المعمارية لأنها تحافظ على الأساس المنطقي للهندسة خارج قاعدة الكود.
تعد ADRs مفيدة لأنها توفر مقرًا ثابتًا لأساس التصميم. إذا لم يكن لدى فريقك تنسيق محدد، فاستعير نموذج ADR بسيطًا: القرار، والسياق، والخيارات التي تم النظر فيها، والمفاضلات، والعواقب.
ركز توثيقك على الفئات التالية:
- قرارات التصميم والبدائل: "اخترنا هنا ذاكرة التخزين المؤقتة ذات الكتابة المباشرة بدلاً من الكتابة المؤجلة لأن اتساق البيانات أكثر أهمية من زمن انتقال الكتابة في تدفق الدفع هذا"
- القيود المعروفة: الديون التقنية، وقيود التوسع، والحلول المؤقتة، أو المجالات التي تحتاج إلى تنظيف في المستقبل
- الافتراضات: تنسيقات الإدخال المتوقعة، أو متطلبات البيئة، أو التبعيات الأولية التي لا يفرضها الكود
- المراجع: روابط إلى التذاكر ذات الصلة، أو طلبات التعليقات (RFC)، أو سجلات قرارات الهندسة (ADR) التي تشرح السياق الأوسع
تحتاج السياقات المختلفة إلى أماكن مختلفة. تلتقط سلاسل الوثائق (Docstrings) النوايا على مستوى الوظائف. تتعامل تعليقات الكود مع المنطق على مستوى الأسطر. توفر أوصاف PR سياقًا على مستوى التغييرات. تتعامل ADRs مع القرارات على مستوى النظام. تساعد رسائل الالتزام أيضًا، ولكن لا ينبغي أن تكون السجل الوحيد لقرار مهم.
نمط سلبي شائع: توثيق كيفية عمل خوارزمية الفرز سطراً سطراً. السؤال الحقيقي هو لماذا تم استخدام فرز مخصص بدلاً من المكتبة القياسية. بالنسبة لمسارات الكود المخصصة، قم بتوثيق القرار الكامن وراء التنفيذ.
ما هي أهم الممارسات الفضلى في مجال التوثيق؟
هناك خمس ممارسات تجعل التوثيق أكثر فائدة بعد انتهاء السبرينت. وتعتمد معظم النصائح الأخرى المتعلقة بالتوثيق على تطبيق هذه العادات أولاً.
- قم بالتوثيق أثناء البرمجة، وليس بعدها. فالسياق يتلاشى بسرعة. بحلول السباق التالي، ستكون قد نسيت البديل الذي رفضته ولماذا. اكتب تعليق "السبب" في نفس الالتزام الذي يحتوي على الكود، وإلا فلن تكتبه على الإطلاق
- استخدم دليل أسلوب متسق. اختر تنسيقًا واحدًا لسلسلة الوثائق (docstring)، مثل أسلوب Google أو أسلوب NumPy أو Javadoc أو JSDoc، وقم بتطبيقه في مراجعة الكود أو فحصه. التناسق أكثر أهمية من التنسيق الذي تختاره. دليل الأسلوب المشترك يزيل السؤال "كيف يجب أن أقوم بتنسيق هذا؟" ويجعل فحص الكود الآلي ممكنًا
- تعامل مع الوثائق كجزء من مراجعة الكود. أضف فحوصات التوثيق إلى قائمة مراجعة طلبات السحب (PR). إذا غيّر طلب السحب (PR) السلوك، يجب على المراجع التحقق من أن الوثائق تعكس التغيير. تطلب وثائق ممارسات الهندسة في Google من المراجعين التحقق مما إذا كان الكود موثقًا بشكل مناسب. استخدم نفس القاعدة داخليًا: إذا غيّر طلب السحب (PR) السلوك، يجب على المراجعين التحقق مما إذا كانت التعليقات وسلاسل الوثائق وملفات README ودفاتر التشغيل لا تزال متطابقة
- احذف الوثائق القديمة. تسبب الوثائق القديمة ضررًا حقيقيًا لأنها توجه القراء نحو التنفيذ أو واجهة برمجة التطبيقات (API) أو العملية الخاطئة. راجع الوثائق كل ثلاثة أشهر أو قبل كل إصدار رئيسي. حدد المسؤولية حتى لا تكون الوثائق مسؤولية الجميع وبالتالي لا تكون مسؤولية أحد
- اجعل الأمثلة قابلة للتشغيل. يجب أن تكون أمثلة الكود سهلة النسخ والتشغيل والاختبار. هذه هي الطريقة الأكثر أمانًا لاكتشاف الانحرافات قبل أن يكتشفها المستخدمون
ما هي الأدوات التي يجب استخدامها لإنشاء وثائق الكود؟
تنقسم أدوات التوثيق إلى مجموعتين: المولدات التقليدية ومساعدات الذكاء الاصطناعي. وتقوم كل منهما بمهام مختلفة.
المولدات التقليدية تحلل التعليقات المنظمة في مصدرك وتنتج مراجع قابلة للتصفح. عادةً ما يعتمد المولد المناسب على لغتك.
| الأداة | اللغة/النظام البيئي | ما الذي تولده |
|---|---|---|
| Javadoc | Java | مرجع واجهة برمجة التطبيقات (API) من تعليقات المستندات |
| JSDoc | JavaScript/TypeScript | مرجع واجهة برمجة التطبيقات (API) من التعليقات المشروحة |
| Sphinx | Python (يدعم لغات أخرى عبر المكونات الإضافية) | مواقع توثيق كاملة من reStructuredText أو Markdown |
| Doxygen | C، C++، Java، Python، وغيرها | وثائق مرجعية متعددة اللغات |
| Godoc | انطلق | تجميع الوثائق من تعليقات المصدر |
تعتمد جودة المخرجات كليًا على سلاسل التوثيق الخاصة بك. فهي تقوم بتنسيق ونشر ما كتبته. ولا تبتكر النوايا المفقودة.
تضيف المساعدات المدعومة بالذكاء الاصطناعي طبقة ثانية. يمكن لـ GitHub Copilot و Cursor و Windsurf صياغة التعليقات وسلاسل الوثائق داخل المحرر. يمكن لـ Mintlify المساعدة في إنشاء وثائق المطورين وصيانتها من الكود والوثائق الموجودة. يركز Swimm على ربط الوثائق الداخلية بتغييرات الكود. يساعد ReadMe و GitBook الفرق على نشر مراجع واجهة برمجة التطبيقات (API) والوثائق الموجهة للمطورين، غالبًا باستخدام ميزات البحث أو التأليف المدعومة بالذكاء الاصطناعي.
وجدت دراسة Stack Overflow أن التوثيق كان فئة أتمتة الذكاء الاصطناعي الأكثر طلبًا، حيث تم ذكرها في حوالي 33.9% من إجابات المطورين المفتوحة. تكون هذه الأدوات في أقوى حالاتها عندما يعرض كود المصدر السلوك بوضوح بالفعل.
تضعف الذكاء الاصطناعي عندما يعتمد التفسير على قرارات اتُخذت خارج قاعدة الكود: سلسلة محادثات على Slack، أو اجتماع تخطيط، أو تذكرة، أو مراجعة حادثة. يمكنه تلخيص الوظيفة. لكنه لا يستطيع معرفة أي القيد كان قابلاً للتفاوض، وأي الخيارات تم رفضها، أو لماذا تم قبول المقايضة.
سير العمل العملي:
- دع الذكاء الاصطناعي يصوغ الهيكل الأساسي: ملخص الوظيفة، والمعلمات، وقيم الإرجاع، والاستثناءات الشائعة
- قارنها بسلوك الكود الفعلي
- أضف السبب: القرار، أو القيد، أو الافتراض، أو البديل المرفوض
- اكتب تقرير ADR للقرارات على مستوى النظام
- لا تنشر المستندات التي تم إنشاؤها بواسطة الذكاء الاصطناعي دون مراجعتها
أين يناسب ClickUp وأين لا يناسب
ClickUp ليس أداة لتوليد الوثائق على مستوى الكود. ولن يحل محل Javadoc أو Sphinx أو JSDoc أو Godoc. بل يساعد في توثيق ما يحيط بالكود: ملفات README، ودفاتر التشغيل، وأدلة التمهيد، ووثائق ADR، وسجلات القرارات التي يجب أن تظل مرتبطة بالمهام والتذاكر وسباقات السرعة التي أنتجتها.
يتيح لك ClickUp Docs صياغة هذه الوثائق جنبًا إلى جنب مع عملك الهندسي، ويمكن لـ ClickUp Brain صياغة مستند من سياق المهمة أو المشروع، ثم يمكن للمطورين إضافة أسباب القرار والقيود والمفاضلات.

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

إذا كانت مشكلتك هي أن "مرجع واجهة برمجة التطبيقات (API) لدينا قديم"، فهذه مشكلة تتعلق بالمولد والمراجعة. ستساعدك أدوات Sphinx أو Javadoc أو JSDoc أو Godoc أكثر من أي أداة مساحة عمل. لا تخلط بين الاثنين.
ما الذي يتغير عندما تقوم الذكاء الاصطناعي بكتابة معظم الوثائق؟
هناك نكتة متكررة في سلاسل المناقشات على r/developersIndia و r/webdev و r/AskProgramming حول الوثائق الهندسية. عندما يسأل أحدهم عن كيفية تعامل الفريق مع الوثائق، يكون الرد الأكثر شيوعًا عادةً هو: "أنا هو الوثيقة."
هذا مضحك لأنه حقيقي. لسنوات طويلة، كان الحل البديل لعدم وجود الوثائق هو الاعتماد على المهندس الذي يصادف أنه يتذكر.
الذكاء الاصطناعي يغير المعايير الأساسية. فهو قادر على صياغة الوثائق الروتينية بسرعة، مما يجعل تبرير القرارات غير الموثقة أكثر صعوبة. عندما يصبح الذكاء الاصطناعي قادرًا على بناء الأجزاء الميكانيكية من مستنداتك في ثوانٍ معدودة، فإن عبارة "سأتذكر ذلك فحسب" لن تكون مقبولة بعد الآن كنظام للتسجيل.
وهذا يحوّل عمل المهندس نحو النوايا والقرارات والمفاضلات: وهي الجوانب التي لا يمكن أن تفسرها صيغة الأجزاء وحدها.
كانت معظم النصائح القديمة المتعلقة بالتوثيق مكتوبة لسير عمل ما قبل الذكاء الاصطناعي. وهي تركز بشكل كبير على أوصاف المعلمات، وتوقيعات الوظائف، وملاحظات الإعداد الشاملة.
يمكن للذكاء الاصطناعي الآن صياغة جزء كبير من هذا العمل. إذا كان المهندسون يقضون معظم وقتهم في إعداد الملخصات الآلية، فإنهم يكرسون اهتمامهم البشري للطبقة الأقل قيمة.
خصص هذا الوقت لتوضيح النوايا: سبب وجود الوظيفة، والخيار الذي تم رفضه، والافتراضات التي يعتمد عليها الكود. هذه هي الملاحظات التي سيحتاجها فريقك المستقبلي، ووكلاء البرمجة بالذكاء الاصطناعي، والمهندس الذي سيورث قاعدة الكود في عام 2027.
إذا كانت مشكلة التوثيق التي تواجهها هي تشتت السياق، فيمكن لـ ClickUp المساعدة في إبقاء سجل القرارات أقرب إلى المهام والمستندات والمشاريع التي أنشأتها.
الأسئلة الشائعة حول توثيق الكود
ما هو ملف README؟
تجتاز ملف README الاختبار الأول عندما يتمكن المساهم من العثور بسرعة على خمسة أشياء: ما الذي يفعله المشروع، وكيفية تثبيته، وكيفية استخدامه، وكيفية المساهمة فيه، وأين يمكن الحصول على المساعدة. إذا كانت الإعدادات مخبأة تحت الشارات أو ملاحظات البنية أو تفاصيل سجل التغييرات، فهذا يعني أن ملف README غير منظم بشكل جيد.
ما الفرق بين تعليقات الكود والوثائق؟
توجد تعليقات الكود داخل ملفات المصدر وتشرح أسطر أو كتل معينة. وعادةً ما توجد الوثائق خارج ملفات المصدر في ملفات README أو مواقع الويكي أو مواقع المراجع التي تم إنشاؤها أو وثائق واجهة برمجة التطبيقات (API). تساعد التعليقات المطور التالي الذي يقرأ وظيفتك. وتساعد الوثائق الشخص التالي الذي يحاول استخدام مشروعك أو تشغيله أو المساهمة فيه.
ما هي طبقة النوايا في توثيق الكود؟
طبقة النية هي الجزء من توثيق الكود الذي يوضح سبب وجود الكود، وليس ما يفعله: القرار الذي تم اتخاذه، والمقايضة التي تم قبولها، والقيود التي دفعت التصميم، والخيار الذي رفضه الفريق. يُظهر الكود السلوك؛ بينما تحافظ طبقة النية على الأساس المنطقي. يمكن لأدوات الذكاء الاصطناعي مثل GitHub Copilot و Mintlify صياغة الطبقة الميكانيكية (أنواع المعلمات، ملخصات الوظائف)، ولكنها لا تستطيع استنتاج طبقة النية من الصيغة. وعادةً ما توجد هذه الطبقة في سجلات قرارات الهندسة المعمارية، أو أوصاف PR، أو التعليقات التي تشرح لماذا بدلاً من ماذا.
كم مرة يجب تحديث وثائق الكود؟
قم بتحديث الوثائق في نفس طلب السحب الذي يغير السلوك الأساسي. إذا تغير توقيع الدالة، يتغير سلسلة الوثائق في طلب السحب هذا. بالنسبة لملفات README ووثائق البنية، قم بالمراجعة مرة واحدة على الأقل لكل إصدار أو كل ثلاثة أشهر. الوثائق القديمة خطيرة لأنها تعلم القراء السلوك أو واجهة برمجة التطبيقات أو العملية الخاطئة.
ما هي الأنواع الأربعة للتوثيق؟
يقسم إطار عمل Diátaxis، الذي يحظى بقبول واسع، الوثائق إلى أربعة أنواع: البرامج التعليمية (الموجهة للتعلم، للمبتدئين)، وأدلة الإرشادات (الموجهة للمهام، للمستخدمين الذين يحلون مشكلة معينة)، والمراجع (الموجهة للمعلومات، للمستخدمين الذين يبحثون عن التفاصيل)، والتفسيرات (الموجهة للفهم، للمستخدمين الذين يرغبون في معرفة السياق). يؤدي خلط هذه الأنواع إلى إنشاء وثائق لا يمكن لأحد استخدامها. قد يؤدي ملف README الذي يحاول أن يكون درسًا تعليميًا كاملاً إلى إخفاء مسار الإعداد. وقد تخفي صفحة مرجعية مكتوبة كأنها مقال استدعاء واجهة برمجة التطبيقات (API).
كيف يمكنك توثيق الكود باستخدام الذكاء الاصطناعي؟
استخدم الذكاء الاصطناعي للطبقة الميكانيكية واكتب طبقة النوايا بنفسك. يمكن لأدوات مثل GitHub Copilot و Cursor و Mintlify صياغة سلاسل الوثائق ووصف المعلمات وقيم الإرجاع وملخصات الوظائف مباشرة في محررك. راجع المسودة مقارنةً بسلوك الكود الفعلي، ثم أضف الأجزاء التي لا يستطيع الذكاء الاصطناعي استنتاجها: الأساس المنطقي للقرار، والقيود التي دفعت إليه، والخيار الذي رفضته، وأي افتراض يعتمد عليه الكود. بالنسبة للقرارات على مستوى النظام، اكتب سجل قرارات الهندسة المعمارية. لا تنشر أبدًا مستندات تم إنشاؤها بواسطة الذكاء الاصطناعي دون مراجعة بشرية.
هل الوثائق التي يُنشئها الذكاء الاصطناعي موثوقة؟
تعد الوثائق التي تم إنشاؤها بواسطة الذكاء الاصطناعي مفيدة للأعمال الميكانيكية مثل وصف المعلمات وقيم الإرجاع وملخصات الوظائف الأساسية، ولكنها لا تزال بحاجة إلى مراجعة بشرية. تتعامل أدوات مثل GitHub Copilot و Cursor و Codeium و Mintlify مع هذه الأمور بشكل جيد. لا يمكن للذكاء الاصطناعي استنتاج سبب إجراء مقايضة ما، أو البدائل التي تم رفضها، أو القيود المتعلقة بالمنتج أو الأعمال أو البنية التحتية التي شكلت التصميم. استخدم الذكاء الاصطناعي لكتابة المسودة الأولى. أضف النوايا والسياق بنفسك.
هل تحتاج كل دالة إلى سلسلة توثيقية؟
لا. تحتاج واجهات برمجة التطبيقات العامة (APIs) وأي وظيفة سيستدعيها مطور آخر إلى سلاسل توثيقية. أما المساعدات الخاصة المستخدمة في ملف واحد، فعادةً لا تحتاج إلى ذلك ما لم تكن المنطقية غير واضحة. إن الإفراط في توثيق الكود البسيط يخلق عبئًا على الصيانة دون إضافة أي وضوح. قم بمطابقة عمق التوثيق مع جمهور الوظيفة.
ما هي أفضل أداة لإنشاء وثائق الكود؟
تعتمد الأداة المناسبة على لغتك. تستخدم فرق Java Javadoc، وتستخدم فرق JavaScript و TypeScript JSDoc، وتستخدم فرق Python Sphinx، وتستخدم فرق Go Godoc، بينما يتعامل Doxygen مع C و C++ والعديد من اللغات الأخرى. يمكن للأدوات المدعومة بالذكاء الاصطناعي مثل Mintlify و Swimm و Copilot و Cursor المساعدة في صياغة أو صيانة الوثائق عبر أجزاء من سير العمل، لكنها لا تحل محل المولدات الأصلية للغة.
ما هو الطول المثالي لملف README؟
يجب أن تكون الوثيقة طويلة بما يكفي للإجابة بسرعة على الأسئلة الأساسية: ما الذي يفعله المشروع، وكيفية تثبيته، وكيفية استخدامه، وكيفية المساهمة فيه، وأين يمكن الحصول على المساعدة. ضع التفاصيل الأعمق المتعلقة بالإعداد والبنية وواجهة برمجة التطبيقات (API) في وثائق مرتبطة أو دلائل فرعية.

