
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 على مر السنين، عملت في جميع أنواع المشاريع - الكبيرة والصغيرة والفوضوية والمفرطة في الهندسة و"المؤقتة" وذات البنية الجيدة المزعومة وكل ما بينهما. ومع ذلك، ظل نمط واحد ثابتًا بشكل مثير للسخرية: التوثيق مفقود دائمًا، أو قديم، أو مدفون في زاوية منسية من Confluence يحرسها ختم زمني لعام 2019. كل مشروع *يدعي* أن لديه توثيقًا. كل فريق *يعد* بالحفاظ عليه محدثًا. وكل مطور يقول بثقة، "لا تقلق، سأكتبه لاحقًا"، وهو ما نعرفه جميعًا، هو ما يعادل التوثيق قول  "الشيك في البريد". بعد مشاهدة هذه الدورة تتكرر مرات أكثر مما أود الاعتراف به، أدركت شيئًا بسيطًا ولكنه صحيح بشكل قاسٍ: 
 
 التوثيق لا يدوم إلا إذا عاش قريبًا من الكود قدر الإمكان - لأن المطورين (بما في ذلك أنا) مخلوقات كسولة. ومن ذلك، جاء إدراك آخر - المشكلة الرئيسية في التوثيق القديم هي حقيقة أن معظم الفرق لا تعتبره جزءًا من دورة التطوير الرئيسية، تاركينها لوقت لاحق أو يكتفون ببضع مواصفات ما قبل التطوير التي كانت لديهم بالفعل في مكان ما في Confluence. لكتابة توثيق هادف، دعنا نناقش أولاً ما هو نوع التوثيق الموجود لمكون برمجي: طرق لتوثيق الكود (التي قد يستخدمها المطورون فعلاً) بمجرد قبولك بأن التوثيق يجب أن يعيش قريبًا من الكود، فإن السؤال التالي هو *كيف* يتم تنظيمه. من الناحية العملية، وجدت أن التوثيق الجيد ليس قطعة أثرية واحدة - إنه نظام بيئي صغير من الطبقات، كل منها يخدم غرضًا وجمهورًا مختلفًا. بالنسبة للمشروع الذي ذكرته (مكتوب بلغة Java + Spring Boot)، حددنا أربعة أنواع رئيسية من المستندات: 1. مواصفات العميل هذه هي مستندات تقليدية يجمعها عادة خبير في المجال. من الناحية المثالية، تكون غنية باللغة الشائعة وتقدم أوصافًا غير مرتبطة بالكود لحالات العمل - بعبارة أخرى، كل ما يحتاجه المهندس لفهم المشكلة المطروحة حقًا. للأسف، في الواقع، غالبًا ما تنتهي هذه المستندات مخزنة في مكان ما في Confluence، مشتركة مع الفريق في بداية المشروع، ثم لا يتم تحديثها تقريبًا مرة أخرى. لا تفهموني خطأ: هذه المستندات *مهمة*. يجب أن يكون استخلاص المعرفة من خبراء المجال أولوية قصوى لأي فريق هندسي. لكن المواصفات تتطور، والمواعيد النهائية تضغط على الجميع، وتصبح تلك المستندات الأصلية ببطء ولكن بثبات أساسًا قديمًا. تنتهي معرفة المتطلبات المتغيرة، والحالات الطرفية، وتحولات المشروع بالعيش في الكود - أو ما هو أسوأ! - في رؤوس كبار المطورين. لمعالجة هذا، توقفنا عن كتابة المواصفات في ملفات Word عشوائية أو صفحات Confluence مخصصة للنسيان وانتقلنا بها إلى أقرب ما يمكن إلى الخط الأمامي:  مستودع الكود. بدأنا بتخزينها كملفات Markdown (.md) داخل المستودع، عادةً في مجلد docs/. في بيئات الخدمات المصغرة الكبيرة، يمكن لهذه المستندات أن تبرر حتى مستودعًا مخصصًا مرتبطًا كوحدة فرعية Git. غالبًا ما يتم تجاهل الوحدات الفرعية، لكنها طريقة قوية للحفاظ على تنظيم أنظمة المستودعات المتعددة. للمزيد من القراءة حول الوحدات الفرعية، أوصي بشدة بمنشور المدونة هذا -  . الرابط 2. README - الباب الأمامي للبشر إذا كانت مواصفات العميل هي الموسوعة، فإن README هو الباب الأمامي. ومع ذلك، فهي واحدة من أكثر قطع التوثيق التي يتم تجاهلها في مشاريع البرامج.  ومن المفارقات أن معظم منصات التحكم في الإصدار - GitHub و GitLab و Bitbucket - تعرض README تلقائيًا في صفحة المشروع الرئيسية. إنها أول شيء يراه أي مطور عند الوصول إلى المستودع. على الرغم من ذلك، غالبًا ما تكون README فارغة بشكل صادم، أو قديمة بشكل مؤلم، أو مليئة بـ "TODO: اكتب التوثيق لاحقًا" المروع، والذي بالطبع لا يحدث أبدًا. ملف README جيد ليس اختياريًا. إنه المستند الوحيد الأكثر احتمالاً للقراءة فعليًا لأنه يتطلب  . ولأنه يقع في جذر المستودع، فإن المطورين أكثر عرضة لتحديثه أثناء العمل على الكود. إنه توثيق يعيش في مسار أقل مقاومة. نقرات صفر يجب أن يجيب ملف README المكتوب جيدًا على أهم الأسئلة التي يطرحها المطور في الدقائق الأولى من مواجهة المشروع: 
 
 
 
 
 
 
  بيان غرض وسياق موجز - لا يوجد هراء تسويقي. ماذا يفعل هذا الخدمة/المشروع/المكون؟ -  تعليمات وقت التشغيل، ومتغيرات البيئة، وإعداد التبعية، وأي أوامر خاصة بالمشروع. كيف أقوم بتشغيله محليًا؟ -  اختبارات الوحدات، اختبارات التكامل، إعداد بيانات الاختبار، وأي أدوات متعلقة بالاختبار. كيف أقوم باختباره؟ -  شرح موجز لتخطيط الدليل، والوحدات الرئيسية، ومكان العثور على الأجزاء المهمة من الكود. كيف يتم تنظيم المشروع؟ -  نصوص النشر، ملاحظات CI/CD، الأذونات المطلوبة، أو فروق المنصة. كيف أقوم بنشره؟  روابط إلى المستندات المنشأة، ملاحظات البنية، مراجع API، والمستندات التصميمية المركزية. أين يمكنني القراءة أكثر؟ - ملف README هو بوابة الدخول إلى المشروع. فهو يحدد التوقعات، ويقلل من وقت الإعداد، ويعطي كل مهندس - جديدًا كان أم ذا خبرة - نقطة توجيه واضحة. عند صيانته بشكل صحيح، يصبح المستند الفردي الأكثر قيمة في المستودع بأكمله. 3. JavaDocs - مستندات يزعجك المترجم للحفاظ عليها JavaDocs - غير مرئية عادة، وغالبًا ما تكون منسية، ولكنها ضرورية للغاية عند حدوث عطل. من الناحية العملية، غالبًا ما يقع توثيق مشاريع Java في طرفين: إما  ، أو   لأن "الكود يوثق نفسه". الحقيقة، كما هو الحال دائمًا، تكمن في مكان ما في الوسط. الإفراط في التعليق على كل سطر تافه عدم وجود تعليقات على الإطلاق بالنسبة لمشروعنا، اتخذنا قرارًا واعيًا بتوثيق  . وهذا يعني: فقط ما هو ضروري حقًا 
 
 
 
 
 استخدام   بحيث تتطابق مصطلحات المجال مع ما كان في مواصفات العمل بالضبط اللغة الشائعة شرح *لماذا* وراء القرارات غير الواضحة، وليس *ماذا* يكشفه الكود بالفعل توثيق فئات المجال الأساسية، والواجهات، وسير العمل المعقدة تجنب جدران التعليقات التي تكرر ببساطة اسم الدالة بشكل مطول JavaDocs، عند استخدامها بشكل صحيح، تعمل كتوثيق على المستوى الجزئي الذي يوضح القصد دون ازدحام الكود. وعلى عكس صفحات Confluence، تأتي JavaDocs مع ميزة مدمجة: 
 
 المترجم يشتكي بالفعل عندما تصبح غير متزامنة. إذا قمت بإعادة تسمية معامل ولكن نسيت علامة JavaDoc، فإن البناء يذكرك. إذا حذفت دالة ولكن تركت مراجع تعليقات قديمة، فإن IDE يضيء مثل شجرة عيد الميلاد. هذا الاحتكاك اللطيف هو بالضبط السبب في أن JavaDocs تميل إلى أن تظل أكثر دقة من أشكال التوثيق الأخرى - فهي مزعجة للإهمال. للحفاظ على كل شيء مركزيًا وتجنب "جزر التوثيق"، استخدمنا أيضًا  . Doxygen Doxygen هي أداة شائعة لتوليد التوثيق في تطوير البرمجيات. بينما تستخدم بشكل أساسي في مجتمع C++، استخدمناها لتجميع JavaDocs في مرجع متسق وقابل للتصفح - صفحة HTML. لديها عدد من الميزات التي لا يقدمها JavaDoc، على سبيل المثال، الرسوم البيانية للفئات للتسلسلات الهرمية وسياق التعاون، والمزيد من صفحات الملخص، والكثير غيرها. هذا أعطانا عرضًا نظيفًا وموحدًا للكود بأكمله دون الاعتماد على تلميحات IDE المتفرقة. 4. كود نظيف - التوثيق الذي لا تحتاج إلى صيانته أخيرًا، شكل التوثيق الأقل تقديرًا هو أيضًا الشكل الذي يحترمه المطورون أقل - حتى يحتاجون إليه حقًا:  الكود النظيف. التعليقات تتقادم. المواصفات تنجرف. ملفات README يتم تجاهلها. JavaDocs قد تصبح قديمة. لكن الكود المكتوب جيدًا - واضح، متعمد، ومعبر - *هو* توثيق. كما قال العم بوب الشهير،  "الكود النظيف يقرأ مثل نثر مكتوب جيدًا." ومن الناحية العملية، هذا يعني: 
 
 
 
 
 
 
 فئات ودوال بأسماء تكشف عن غرضها وظائف تقوم بشيء واحد وتقوم به بشكل جيد مصطلحات المجال المستخدمة باستمرار في كل مكان لا ذكاء لأجل الذكاء لا "سلوكيات مفاجئة" مخفية داخل آثار جانبية لا تجريدات عميقة غير ضرورية تتطلب درجة دكتوراه للفهم الكود النظيف هو القطعة الأثرية الوحيدة المضمونة للبقاء على قيد الحياة بعد إعادة التنظيم، والدورات، وتغيير الموظفين، والفوضى التنظيمية. إنه دائمًا متزامن مع سلوك النظام لأنه - *هو* سلوك النظام. قاعدة بسيطة ظهرت لنا بمرور الوقت:  إذا كنت بحاجة إلى فقرة من التعليقات لشرح دالة، فإن المشكلة الحقيقية هي الدالة. عندما يكون الكود معبرًا، يصبح كل شيء آخر أسهل → تصبح JavaDocs أخف وأكثر تركيزًا → يتقلص ملف README لأن الإعداد يصبح واضحًا → تصبح المواصفات أوضح لأن نموذج المجال يعكس مفردات العمل. الكود النظيف لا يلغي الحاجة إلى التوثيق؛ بل  . يرسيه يضمن أن جميع أشكال التوثيق الأخرى - المواصفات، وملفات README، و JavaDocs - تعزز الحقيقة بدلاً من التعويض عن التنفيذ غير الواضح. في النهاية، الكود النظيف هو التوثيق الذي لا يتطلب صيانة، ولا تكامل CI، ولا أدوات. إنه التفسير الأكثر صدقًا وموثوقية لما يفعله النظام بالفعل. جمع كل شيء معًا - خط أنابيب توثيق حي بعد تحسين طريقة كتابتنا للتوثيق، كانت الخطوة الأخيرة هي التأكد من أنه لم يتم إنشاؤه فحسب - بل تم تسليمه باستمرار وكان متاحًا دائمًا. ولهذا، قمنا ببناء خط أنابيب توثيق حول مواصفاتنا وملفات README و JavaDocs إلى   موحدة. بوابة توثيق حية نظرًا لأننا أردنا أن يعيش توثيقنا قريبًا من الكود قدر الإمكان، قررنا نشر كل شيء عبر  ، مما منحنا حلاً استضافة سهلاً، ومتحكمًا في الإصدار، مرتبطًا مباشرة بالكود المصدري. GitHub Pages ليست خاصة بـ GitHub (GitLab، على سبيل المثال، لديها أيضًا GitLab Pages) - إنها ميزة رائعة أخرى لأنظمة التحكم في الإصدار الشائعة التي أوصي بها لمزيد من القراءة -  . GitHub Pages الرابط لتجميع كل شيء في مجموعة من الصفحات المتماسكة، استخدمنا  Sphinx. Sphinx هو مولد توثيق قوي مكتوب بلغة Python. يأخذ الملفات المصدر المكتوبة بـ reStructuredText أو Markdown ويترجمها إلى تنسيقات إخراج مختلفة، بما في ذلك HTML و PDF و ePub. تولى Sphinx الهيكل والتنقل والتصميم. قامت Doxygen بتغذية Sphinx بـ JavaDocs المولدة تلقائيًا باستخدام المكون الإضافي  ، مما منحنا مرجع API قابلاً للتصفح بالكامل مباشرة من الكود المصدري. وفي الوقت نفسه، عمل ملف README الرئيسي كنقطة دخول فورية للمطورين الذين يستكشفون المستودع، ويربط بسلاسة بموقع التوثيق المنشأ. Breathe كل دمج في الفرع الرئيسي أدى إلى تشغيل وظيفة CI أعادت بناء المستندات، مما يضمن أن البوابة تعكس أحدث تغييرات الكود، وتحديثات API، والقرارات التصميمية. لم يعش شيء في عزلة. لم يتطلب شيء مزامنة يدوية. والأهم من ذلك - لم يكن أي شيء يبعد أكثر من نقرة واحدة. هذا حول توثيقنا من قطعة أثرية ثابتة إلى نظام بيئي محدث باستمرار استخدمه المطورون فعليًا، لأنه تم دمجه مباشرة في سير عملهم اليومي وعاش بجانب الكود. الخلاصة - التوثيق مسؤوليتنا، وليس عبئنا في نهاية المطاف، كتابة التوثيق ليست اختيارية. إنها جزء من عملنا كمهنيين هندسيين. يعتمد زملاؤنا المستقبليون عليه. الإعداد يعتمد عليه. الصيانة والموثوقية وحتى الوضوح المعماري يعتمدون عليه. لكن قبول هذه المسؤولية لا يعني أن التوثيق يجب أن يكون مؤلمًا. من خلال إبقاء المستندات قريبة من الكود، وأتمتة ما يمكن أتمتته، والاعتماد على أدوات ذكية مثل Markdown و JavaDocs و Doxygen و Sphinx، فإننا نزيل الاحتكاك الذي يقتل عادة جهود التوثيق. نحول شيئًا يبدو تقليديًا كمهمة إلى امتداد طبيعي للتطوير اليومي. وعندما نقارن ذلك بالكود النظيف، وملفات README الجيدة، والمواصفات الغنية بالمجال، يصبح النظام البيئي بأكمله مستدامًا ذاتيًا. التوثيق لا يحتاج إلى أن يكون مثاليًا - بل يحتاج فقط إلى أن يكون متاحًا ودقيقًا وحيًا. عندما نبني أنظمة تشجع المطورين على تحديث المستندات بسهولة كتابتهم للكود، يستفيد الجميع: الفريق، المنتج، والأهم من ذلك، الشخص المسكين الذي يرث المشروع بعد ستة أشهر. التوثيق الجيد لا يجعلنا أقل كسلًا. إنه فقط يجعل كوننا كسالى متوافقًا مع بناء برامج رائعة.

The is an opinion piece based on the author’s POV and does not necessarily reflect the views of HackerNoon.

Read My Stories

تم إنتاج هذا الصوت باللغة الأصلية للقصة!

إذا استغرقت وثائقك نقرتين لفتحها، فتهانينا - فقد تم تحديثها بالفعل

About Author

تعليقات

شنق العلامات

تم تقديم هذه المقالة في

Related Stories

I2ShowSpeed With My HackerNoon Articles on Bitcoin

Anomaly Detection of Time Series Data using Machine Learning & Deep Learning

Top 10 Android App Development Companies in India & US

30 Top Blockchain Development Companies in 2019

I2ShowSpeed With My HackerNoon Articles on Bitcoin

Anomaly Detection of Time Series Data using Machine Learning & Deep Learning

Top 10 Android App Development Companies in India & US

30 Top Blockchain Development Companies in 2019

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps