كيف تكتب تعليقات جيدة على الكود: "لماذا" وليس "كيف"

مرحبا هبر! أقدم انتباهكم إلى ترجمة مقال "كتابة تعليقات جيدة: لماذا ، وليس كيف" بقلم جاك فرانكلين.







غالبًا ما يُعتبر التعليق على الكود في بيئة البرمجة مضيعة للوقت أو إشارة إلى أنه يمكن تحسين الكود. إليك اقتباس من ملف CONTRIBUTING.md الذي وجدته على GitHub (وهناك الكثير من هذه الأمثلة):

يجب تجنب التعليقات. إذا كان لا يمكن فهم الكود الخاص بك بدون تعليقات ، أعد كتابته لشرح نفسه.

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

يجب أن يحتوي كل سطر من التعليمات البرمجية على تعليق يشرح ما يفعله. سيتم الحكم على عملك في الدورة وفقًا لهذا المعيار.

لذلك ، لنفترض أنك طالب مخبوز حديثًا بدأت للتو هذه الدورة التدريبية. مذا ستفعل؟ التعليق على الكود بالطبع!

//      bar
const inputValue = process.ENV.bar

//     2
const newValue = inputValue * 2

//     square
const finalValue = square(newValue)

//         
const square = (x) => x * x

الأشخاص الذين يقولون أن التعليقات سيئة يفكرون في الواقع في مثل هذه التعليقات. وهم على حق تماما! التعليقات مثل تلك المذكورة أعلاه التي تجيب على السؤال "كيف؟" في البرمجة عديمة الفائدة تمامًا. كل هذه التعليقات لم تضف أي شيء إلى الكود لا يمكن فهمه من الكود نفسه.

أجب عن السؤال "لماذا؟"

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



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



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



أردت أن أجد مثالًا أعرضه هنا ، لذلك ذهبت إلى براري قاعدة أكواد React للعثور على شيء ما. لست بحاجة إلى أن تكون مطور React لمعرفة ذلك. إذن ، هذا هو الكود الذي أود إبرازه:

//  key     .    , 
//  key      (, <div {...props} key="Hi" />
//  <div key="Hi" {...props} /> ).     key,   ,
//      jsxDEV   , 
// <div {...props} key="Hi" />,       ,
//    key   . 
if (maybeKey !== undefined) {
  key = '' + maybeKey
}

( وهنا رابط لها على جيثب ).



انتبه إلى الكود نفسه:

if (maybeKey !== undefined) {
  key = '' + maybeKey
}

ليس من الصعب معرفة ما يفعله. إذا كان مفتاح mightKey غير محدد ، نقوم بتعيين قيمة مفتاح ربما إلى مفتاح. ملاحظة: هذه خدعة JavaScript صغيرة '' + maybeKeyلتحويل محتويات mightKey إلى سلسلة.



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



إذا كنت تريد إلقاء نظرة على أي تعليق تركته في الكود الذي كتبته ، فإليك تعليق (TypeScript / Closure Compiler) . هذا مثال جيد على نوع التعليقات التي أجدها قيّمة للغاية.



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