ورقه وقلم و خلينا نتكلم عن توثيق المشروع الخاص بك (Documentation)، أولاً وقبل كل شيء، فيه طرق كتير علشان تساعدك توثق مشروعك البرمجي منها (READMEs, Code Comments, How-to guides, tutorials, getting started guide, API documentation) وغيرهم كتير. لكن خلينا النهارده ندردش شويه عن نوع واحد وهو الجزء اللي بيكون مخفي بين سطور الكود، واللي ممكن يكون سر نجاح أو فشل المشروع في التواصل مع المطورين الآخرين وهو Code Comments.
الهدف الرئيسي من الCode Comments
الهدف الرئيسي من ال Code Comments هو إنارة الطريق للي هيشوف الكود بعدك، يعني تخليه يفهم ليه اخترت الطريق ده او ليه استخدمنا طريقه معينه او الجورزم معين مش ازاي نفذته , لان ببساطة إجابة سوال ازاي نفذت الفكره أنت مجاوب عليه في الكود 😄( ولا أنت مش كاتب Clean Code👀). مثال:
- ❌ looping over the list to print items
- ✅ looping over the list to filter and display only relevant data
توضيح Function أو Concept معقد
لو بتوضح Function أو Concept معقد، حط مثال على شكل الOutput المتوقع، ده هيسهل على اللي بعدك يفهم المطلوب بشكل أسرع.
- ❌ the function calculates tax
- ✅ the function calculates tax, e.g., input 100, output will be 115 with 15% tax
الدقة في الكتابة وتحديث التعليقات باستمرار
من الأمور المهمة كمان، إنك تكون دقيق وتحدث التعليقات دايمًا. لو عدلت في الكود، يبقى لازم تعدل في التعليقات كمان. تخيل لو معملتش كده، اللي هيجي بعدك هيتلخبط وممكن يبني على معلومات غلط!
الطول المناسب للتعليق
متطولش أوي في التعليقات اللي بتكتبها. خليك مختصر وواضح، واشرح الأجزاء المعقدة بس، مش كل سطر كود كتبته. لأن ببساطة التعليقات الكتير ممكن تخلي فيه زحمة في الكود وده يخليه صعب القراءة.
- ❌ this code checks the value of x then compares it with y and then prints the result if it's greater`
- ✅ evaluate x against y and print if x is greater`
كتابة التعليقات في وقت كتابة الكود وليس بعدها!
حاول دايما تكتب التعليقات وانت بتكتب الكود , مش بعد ما تخلص الكتابة ده هيساعدك علي انك تتجنب النسيان او تفاصيل مهمة
الخاتمة
وهنا بقى نيجي لنقطة جدال كبيرة في عالم التكنولوجيا. فيه ناس كتير بتقول إن الCode Comment هو مجرد عذر لكود مكتوب بشكل مش منظم أو مش واضح، وإن الكود المكتوب كويس لازم يكون شارح نفسه بنفسه، وده اللي بيسموه "Self-Documenting Code".
واللي ميعرفش ايه هو ال Self-Documenting Code فهو مفهوم في عالم البرمجة بيتكلم عن كتابة الكود بطريقة تخليه يشرح نفسه بنفسه من غير الاحتياج لتعليقات مفصلة. الهدف من الكود الذاتي التوثيق هو تحقيق الوضوح والفهم السريع للكود من قبل المطورين الآخرين، منها استخدام أسماء متغيرات ودوال واضحة ومعبره.
وأنا هنا بسألك، إيه رأيك في الكلام ده؟ هل أنت مع الفريق اللي بيقول التعليقات مهمة ولا الفريق اللي بيقول لو الكود كويس مش هيحتاج تعليقات؟ شاركنا برأيك في التعليقات، ويلا نفتح النقاش!
