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

Question

يستخدم بعض زملائي تعليقات خاصة على إصلاحات الأخطاء الخاصة بهم، على سبيل المثال:

// 2008-09-23 John Doe - bug 12345
// <short description>

هل لهذا معنى؟
هل تعلق على إصلاحات الأخطاء بطريقة خاصة؟

أخبرونى من فضلكم.

Answer 1

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

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

Answer 2

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

Answer 3

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

[معرف الخطأ] مشكلة في مربع حوار xyz.نقل رمز التحجيم إلى ABC والآن تهيئة في وقت لاحق.

ثم في أداة تعقب المشكلات الخاصة بي، سأفعل شيئًا مثل:

ثابت في قائمة التغيير 1234.

نقل رمز التحجيم إلى ABC والآن تهيئة في وقت لاحق.

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

Answer 4

فقط إذا كان الحل ذكيًا بشكل خاص أو يصعب فهمه.

Answer 5

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

// Glenn F. Henriksen (<email@company.no) - 2008-09-23
// <Short description>

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

(نعم، لسوء الحظ، في أغلب الأحيان ليس لديهم التحكم بالمصادر...بالنسبة للأشياء الداخلية أستخدم تتبع TFS)

Answer 6

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

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

Answer 7

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

Answer 8

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

// <date> [my name] - Bug xxxxx happens when the foo parameter is null, but
// some customers want the behavior.  Jump through some hoops to find a default value.

في حالات أخرى، تكون رسالة التزام التحكم بالمصدر هي ما أستخدمه للتعليق على التغيير.

Answer 9

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

Answer 10

يعد هذا النمط من التعليق ذا قيمة كبيرة في بيئة متعددة المطورين حيث توجد مجموعة من المهارات و/أو المعرفة التجارية عبر المطورين (على سبيل المثال.- في كل مكان).

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

أوه، وملاحظة من التجربة حول تعليقات "لقد وضعت ذلك للتو في نظام التحكم بالمصدر":

وإذا لم يكن في المصدر، لم يحدث.

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

عادةً ما أضعه هناك أولاً، ثم أقص وألصق نفس التعليق عندما أتحقق منه.

Answer 11

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

Answer 12

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

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

في بعض الأحيان، يؤدي إصلاح الأخطاء إلى جعل الأمور تبدو غريبة، أو يكون إصلاح الأخطاء بمثابة اختبار لشيء خارج عن المألوف.إذن قد يكون من المناسب أن يكون لديك تعليق - عادةً ما يجب أن يشير التعليق إلى "رقم الخطأ" من قاعدة بيانات الأخطاء لديك.على سبيل المثال، قد يكون لديك تعليق يقول "الخطأ 123 - حساب السلوك الغريب عندما يكون المستخدم في دقة شاشة 640 × 480".

Answer 13

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

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

Answer 14

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

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

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

جمعية البناء الخيرية.

Answer 15

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

إذا لم يتم حل الخلل، التعليق خاطئ.ثم فمن المنطقي.:) لذا فقط اترك مثل هذه التعليقات إذا لم تقم بحل الخطأ حقًا.

Answer 16

لتحديد موقع التعليق المحدد الذي نستخدمه DKBUGBUG - مما يعني أنه يمكن تحديد هوية الإصلاح والمراجع الخاصين بـ David Kelley بسهولة، وبالطبع سنضيف التاريخ وأرقام تتبع أخطاء VSTS الأخرى وما إلى ذلك جنبًا إلى جنب مع هذا.

Answer 17

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

بدلا من ذلك:

// $ تاريخ $ اسم $ ticket // تعليق مفيد للروح الفقيرة التالية

اريد ان افعل هذا:

// تعليق مفيد للروح المسكينة القادمة

Answer 18

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

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

هتافات،

روب

Answer 19

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

في الكود الخاص بي، نادرًا ما أعلق على إصلاحات الأخطاء.

Answer 20

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

تذكر أنه لا يوجد شيء اسمه أخطاء، بل فقط اختبار غير كافٍ.

Answer 21

نظرًا لأنني أقوم بأكبر قدر ممكن من TDD (كل شيء آخر هو انتحار اجتماعي، لأن كل طريقة أخرى ستجبرك على العمل لساعات طويلة)، نادرًا ما أقوم بإصلاح الأخطاء.

في أغلب الأحيان أقوم بإضافة ملاحظات خاصة مثل هذه إلى الكود:

// I KNOW this may look strange to you, but I have to use
// this special implementation here - if you don't understand that,
// maybe you are the wrong person for the job.

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