هل من الأفضل أن أكتب تعليقًا يشرح فكرة الكود ككل، أم أكتب تعليقًا على كل سطر من الكود؟

وعليكم السلام ورحمة الله تعالى وبركاته،

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

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

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

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

وعليكم السلام ورحمة الله وبركاته.

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

فمثلا عندما يكون الكود واضح في تنفيذه أى ليس معقدا لكن يحتاج إلى شرح للسياق أو الغرض العام منه فهنا الأفضل كتابة تعليق واحد يشرح فكرة الكود كاملا وما الذي يقوم به

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

الف شكراا جدا لحضرتكم

جزاكم الله كل خير