ما هي نسبة الكود الذهبي/التعليق؟[مغلق]

https://stackoverflow.com/questions/111563

02-07-2019
|

سؤال

هل هناك نسبة رمز/تعليق تعتبرها علامة على صحة الكود الجيدة (السيئة)؟

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

(أدرك أنه لا توجد نسبة "صحيحة" لكل مشروع، وقد تكون هناك مشاريع سيئة للغاية تظهر هذه النسبة الذهبية النظرية.ما زال...)

المحلول

يجب أن تكون التعليقات نادرة جدًا وقيمة، وأن تعبر دائمًا تقريبًا عن "السبب" وليس "الكيفية" أبدًا (الاستثناء هو عندما تكون "الكيفية" معقدة ولا يمكن تمييزها بسهولة من الكود).

يعد كل تعليق بمثابة إشارة إلى أنك قد تحتاج إلى إعادة البناء لجعل غرض الكود أكثر وضوحًا.قد يصبح كل تعليق قديمًا بمجرد كتابته.

ليس لدينا أي تعليقات تقريبًا باستثناء تعليقات XML في موقعنا مشروع xUnit.net, ، لكن بعض الناس يبدو أن الكود واضح وسهل القراءة.:)

نصائح أخرى

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

لفهم الخلل عليك أن تعرف:

ماذا يجب الكود يفعل (لا ماذا الكود يفعل) ولماذا.
عقد كل وظيفة.على سبيل المثال، إذا كان هناك NullPointerException فأين الخطأ؟في الوظيفة أم في وظيفة الاستدعاء؟
في كل عملية اختراق، يجب وصف كيفية ظهور المشكلة (إصدار اللغة، نظام التشغيل، إصدار نظام التشغيل).على سبيل المثال، لدينا العديد من الاختراقات لجهاز Java VM القديم الذي لم يعد مدعومًا بعد الآن.لكننا لسنا متأكدين من إمكانية إزالته لأننا لا نعرف كيفية إعادة إنتاجه.

لدينا نسبة 2-3%، وهي نسبة قليلة جداً.أعتقد أن نسبة 10% تعتبر جيدة للمشاريع الكبيرة أو طويلة الأمد.

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

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

أطيب التحيات

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

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

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

القضية والنقطة:

// Delete the helloworld file
exec("rm -f helloworld.txt")

لن يتم التغيير إلى:

exec("rm -rf /")

من غير المحتمل، وأنا أعلم، ولكن حتى بعض جيد من المعروف أن المطورين يغيرون المنطق بسبب لا يبدو صحيحا وليس بسبب وجود خطأ أو تغيير في المتطلبات.

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

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

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

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

LOC / LOcomment = yearsofexp / 5

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

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

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

النسبة المثالية عندي هي صفر.ومع ذلك، فإن العالم أقل من المثالي، لذلك أقبل التعليقات عندما لا تكون هناك طريقة أخرى لتوصيل فكرة مهمة.

يجب أن تكون هناك تعليقات حيث تشعر أنها ضرورية.لا أكثر ولا أقل.

قم بالتعليق على الأجزاء التي تشعر أنك قد لا تفهمها بعد أكثر من 6 أسابيع من الاستراحة عند النظر مرة أخرى في الكود

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

النسبة الذهبية للتعليق/الرمز هي تقاطع

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

يوضح هذا أيضًا سبب اختلاف هذه النسبة لكل مشروع وكل فريق.

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

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

على سبيل المثال، يمكنك إلقاء نظرة على مقاييس مختلفة لمصدر Linux Kernel.

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

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

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

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

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

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

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

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

لا يمكنك فرض نسبة ثابتة من التعليمات البرمجية/التعليقات وإلا ستنتهي من التعليمات البرمجية المليئة بالضوضاء مثل:

// Add one to i
i++;

الذي يحجب الكود فقط.

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

قم بتشغيل عقلية المشرفين لديك وفكر في ما ترغب في رؤيته موصوفًا فيما يتعلق بالكود الذي كتبته للتو.

هث.

هتافات،

روب

التعليقات لها 3 استخدامات، IMO:

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

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

توجد مناقشة ممتازة لتعليقات التعليمات البرمجية في كتاب Steve McConnells () Code Complete (لدي الطبعة الأولى ولكني أعتقد أنها الآن طبعة ثانية) نص الرابط)

باختصار، فهو يعزز ما ذكرته الإجابات الأخرى - يجب أن يكون نادرًا ويصف لماذا لا كيف - إذا كان بإمكانك إعادة صياغة أسماء المتغيرات والطرق لاستبدال التعليقات، فيجب تفضيل ذلك - مع تقديم معظم IDE نوعًا من التحسس (أو كما قلت سمعت ذات مرة أن Don Box يصفها بأنها - intellicrack نظرًا لإدمانها) لا يوجد سبب لاقتطاع أسماء المتغيرات/الطرق عندما تكون النسخة الأطول والأكثر وضوحًا من شأنها توصيل غرضها بشكل أكثر وضوحًا

0/0 ; zero divided by zero
Runtime error (func=(main), adr=3): Divide by zero

أمر ضمني "افعل ما أعنيه" مع تعليق "لا تعليق"؟

لا توجد مثل هذه النسبة.

عادةً، يجب أن تكون التعليقات موجودة فقط في المواقف التي قد يكون فيها شيء ما غير واضح حقًا، مثل

// Do not Dispose!
SPSite site = properties.Feature.Parent as SPSite;

من ناحية أخرى، إذا كنت تبيع الكود لشخص ما، فسوف يحتاج إلى أكبر عدد ممكن من التعليقات.تصوير بيع محرك ثلاثي الأبعاد أو بعض البرامج الوسيطة للألعاب الأخرى التي لا تحتوي على تعليقات.بالتأكيد، وثائق API وما إلى ذلك.تعد جزءًا كبيرًا من هذه البرامج الوسيطة أيضًا، ولكن التعليمات البرمجية المعلقة الجيدة تؤتي ثمارها أيضًا.لا تزال أشياء مثل "Add 1 to i" غير مرغوب فيها للغاية، ولكن شيئًا مثل "CreateDevice() سيتحقق أولاً مما إذا كان DirectX 10 متاحًا ويعود إلى جهاز DirectX 9 إذا لم يكن كذلك"، يمكن أن يكون مفيدًا حقًا، حتى لو كان تافهًا انظر من الكود.

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

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

بين 3% و9.5%، أكثر أو أقل

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

التعليقات تجعل حياتك أسهل لأنه من المحتمل أنك ستفكر، ما الذي كنت أفكر فيه بحق الجحيم عند كتابة هذا!

مرخصة بموجب: CC-BY-SA مع الإسناد

لا تنتمي إلى StackOverflow