كتابة التعليقات في الكود: الجيد والسيئ والقبيح.

أوقفني إذا سمعت هذا من قبل ...

"الشفرة الجيدة هي التوثيق الذاتي."

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

إنها مبتذلة.

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

هل هذا صحيح؟ نعم .

هل هذا يعني أنه لا يجب عليك أبدا التعليق على التعليمات البرمجية الخاصة بك؟ لا .

في هذه المقالة سنلقي نظرة على الأشياء الجيدة والسيئة والقبيحة عندما يتعلق الأمر بالتعليق على التعليمات البرمجية الخاصة بك.

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

تعليقات التوثيق

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

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

فيما يلي مثال لتعليق التوثيق من مكتبة JavaScript شائعة تسمى Lodash.

إذا قارنت هذه التعليقات بوثائقها عبر الإنترنت ، فسترى أنها مطابقة تمامًا.

إذا كتبت تعليقات على الوثائق ، فيجب عليك التأكد من أنها تتبع معيارًا ثابتًا ويمكن تمييزها بسهولة عن أي تعليقات توضيحية مضمنة قد ترغب أيضًا في إضافتها. تتضمن بعض المعايير والأدوات الشائعة والمدعومة جيدًا JSDoc لـ JavaScript و DocFx لـ dotNet و JavaDoc لـ Java.

الجانب السلبي لهذه الأنواع من التعليقات هو أنها يمكن أن تجعل التعليمات البرمجية الخاصة بك "مزعجة" للغاية ويصعب قراءتها لأي شخص يشارك بنشاط في الحفاظ عليها. الخبر السار هو أن معظم محرري الشفرات يدعمون "طي الكود" مما يسمح لنا بتقليص التعليقات حتى نتمكن من التركيز على الكود.

تعليقات توضيحية

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

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

إليك مثال على تعليق توضيحي سيء - رغم أنه مسل للغاية -.

/* * Replaces with spaces * the braces in cases * where braces in places * cause stasis.**/ $str = str_replace(array("\{","\}")," ",$str);

بدلاً من تزيين عبارة مربكة قليلاً بقافية ذكية - في أبعاد البرمائيات ، لا أقل - كان من الأفضل بكثير أن يقضي المؤلف وقتًا في وظيفة تجعل الكود نفسه أسهل في القراءة والفهم. ربما تم removeCurlyBracesاستدعاء دالة مسماة من دالة أخرى مسماة sanitizeInput؟

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

هل تريد حقًا أن تكون المسؤول عن سرقة جميع المبرمجين في المستقبل من متعة قراءة هذا القافية الصغيرة الذكية؟ كان معظم المبرمجين يضحكون ويتقدمون ، متجاهلين رائحة الكود.

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

مثل ، لا تفعل هذا الهراء:

/*set the value of the age integer to 32*/int age = 32;

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

يحدث هذا عادةً عندما تحتاج إلى إضافة سياق إلى حل غير بديهي.

إليك مثال جيد من Lodash:

function addSetEntry(set, value) { /* Don't return `set.add` because it's not chainable in IE 11. */ set.add(value); return set; }

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

أحيانًا يكون هذا المبرمج الآخر هو نفسك في المستقبل.

في تلك الحالات ، من الأفضل توفير الوقت والحرج على الجميع وترك تعليق.

يلتقط التعليق الوهمي التالي هذا السيناريو تمامًا:

/**Dear maintainer: Once you are done trying to 'optimize' this routine,and have realized what a terrible mistake that was,please increment the following counter as a warningto the next guy: total_hours_wasted_here = 42**/

مرة أخرى ، ما ورد أعلاه يتعلق بالمرح أكثر من كونه مفيدًا. لكن يجب أن تترك تعليقًا يحذر الآخرين من اتباع "حل أفضل" يبدو واضحًا ، إذا كنت قد حاولت بالفعل ورفضته. وعندما تفعل ذلك ، يجب أن يحدد التعليق الحل الذي جربته ولماذا قررت رفضه.

إليك مثال بسيط في JavaScript:

/* don't use the global isFinite() because it returns true for null values*/Number.isFinite(value)

القبيح

إذن ، نظرنا إلى الخير والشر ، ولكن ماذا عن القبيح؟

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

اعمل بقواعد تعليمات برمجية كافية وستصادف تعليقات تتراوح من الساخرة والكئيبة إلى المظلمة والحيوية.

أشياء مثل ما يبدو غير ضار ...

/*This code sucks, you know it and I know it. Move on and call me an idiot later.*/

... ليعني بصراحة

/* Class used to workaround Richard being a f***ing idiot*/

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

لا تفعل هذا.

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