كيفية إقناع الناس إلى تعليق التعليمات البرمجية الخاصة بهم [مغلقة]

https://stackoverflow.com/questions/159597

03-07-2019
|

سؤال

ما هي حجج جيدة لإقناع الآخرين التعليق التعليمات البرمجية الخاصة بهم?

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

إذا كنت ضد التعليق, يمكنك ترك تعليق.يجب أن تكون هذه الموارد من أجل الناس الذين يحاولون إقناع الناس إلى تعليق القانون ، وليس خلاف ذلك.:-)

المحلول

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

نصائح أخرى

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

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

وتبين لهم رمز الخاصة بهم من قبل 6 أشهر. إذا لم يتمكنوا من فهم وتحديد بالضبط ما تقوم به في حدود 2 إلى 4 دقائق، وربما بذلت وجهة نظرك.

ورأيي:

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

وأنا من محبي تعليقه لماذا، وليس ما. إذا لم يكن من الواضح لماذا كود يستخدم نهج واحد على الآخر، والتعليق عليه. إذا كان لديك لإضافة متغير غير المستخدمة الإختراق للالتفاف خلل مترجم، والتعليق لماذا. لكن تعليقات مثل "// الاتصال بقاعدة بيانات" هي علامات من التعليمات البرمجية سيئة أو سياسات سيئة. وهناك طريقة اسمه ConnectToDatabase () هو أفضل بكثير. وإذا كان لديه "// تحديد DB الخادم IP" في ذلك، وربما ينبغي أن يتم سحبها إلى أسلوب المسمى "DetermineDbServerIPAddress ()".

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

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

تعطي لهم بعض (~500 خطوط الحد الأدنى) الرهيبة ، uncommented معكرونة-رمز ريفاكتور.تأكد من المتغيرات غير اسمه منطقيا.فاصل اختياري.

ونرى كيف أنها مثل ذلك!

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

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

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

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

شرح ما تفعله.رمز الجودة يجب أن تفعل أكثر من هذا العمل بالنسبة لك على الرغم من.
والأهم من ذلك, شرح لماذا كنت تفعل شيئا!لقد رأيت الكثير من التعليمات البرمجية التي يقول بالضبط ما تفعله مع أي فكرة حقيقية لماذا المطور (للأسف لي أكثر من مرة) يعتقد أنها فكرة جيدة في المقام الأول.

وذكرهم أن قراءة رمز يمكن نقول لهم إلا ما رمز <م> لا ، وليس ما هو عليه <م> من المفترض القيام به.

إذا أنت أو مطورين آخرين لم أقرأ رمز كاملة (أو رمز كاملة 2 ) ثم بعد وقف ما تقومون به وقراءته.

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

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

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

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

وفي نهاية اليوم إذا كان لديك الذهاب لقضاء بعض الوقت <م> جعل الأمور في نصابها الصحيح هو أفضل بكثير قضيت وقتك إعادة بيع ديون رمز لضمان واصفا الذاتي كما reasonablly لأنها يمكن أن تكون أكثر من مجرد الكتابة تعليقات. مثل هذا توفيرنا يؤتي ثماره في طرق أخرى كتحديد قطع مشتركة من التعليمات البرمجية.

عن يجدر الأخذ في الاعتبار أيضا أن العديد من المطورين الكثير من الخير يفضلون الكتابة هش نظيفة C #، جافا، أيا كان من لغات البشر أقل بكثير دقيقة مع كل الافتراضات والغموض التي لديهم. لن يصدق معظم الناس مع الحس السليم يعرف كم التفاصيل هي ما يكفي من التفاصيل ولكن المطورين جيدة ليست "معظم الناس". ولهذا السبب نحن في نهاية المطاف مع تعليقات مثل \\adds a to b and store it in c (طيب أن يكون شديد جدا ولكن تحصل على نقطة واحدة).

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

وأنا لا يجري المتعرج في لكم، ولكن يجب أن أعيد صياغة السؤال ليكون <م> كيف يمكنك ان تقنع مطورين آخرين للعمل كفريق واحد؟

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

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

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

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

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

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

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

وأقل ما هو أكثر.

والتأكيد على النوعية على الكمية.

في فريقي، وكان هناك دفع للتعليق كل شيء في بعض API ل. بدأ بعض المطورين باستخدام أداة من شأنها أن تولد تعليق تلقائيا من خلال النظر في أسماء أسلوب والتوقيعات.

وعلى سبيل المثال:

/// <summary> /// Gets the Person. /// </summary> /// <returns> /// A Person /// </returns> public Person GetPerson() { }

هل تفكر في النفايات أكبر من العقارات الشاشة؟ يمكنك التفكير في النفايات أكبر من دورات الدماغ من قراءة التعليقات التي لا توفر أية معلومات جديدة؟

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

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

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

class User { getUserName() { /* code here */ } }

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

يجب أن تكون
وتعليقات شامل، وكتب على مستوى النية (لماذا لا كيف)، ونادرة.

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

ويعتمد على مدى قوة لديك ...

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

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

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

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

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

لديك أيضا إلى التفريق بين نوعين مختلفين التعليقات هنا:

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

تعليقات الداخلية (في التعليمات البرمجية المصدر):يمكنك أن تطلب منهم أن يفسر أي وظيفة لديهم مشفرة, مجرد اختيار وظيفة مع حقا عالية cyclomatic مستوى التعقيد, و انظر لهم النضال حول كل رمز مختلف مهام سير العمل واتخاذ المتفرعة ;)

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

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

"كتابة رمز" = "كتابة تسلسل الأوامر في لغة خاصة" + "كتابة تعليقات"

يجب أن يكون بديهيا التعليق رمز حين كتابة هذا التقرير!هل سبق و علق التعليمات البرمجية التي هي بالفعل 3 أو 4 أشهر من العمر ؟ (بالطبع لديك, و كان كل شيء ولكن متعة!)

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

وJames كوران I 100٪ نتفق! أستطيع أن أقرأ التعليمات البرمجية الخاصة بك ومعرفة ما قلت المترجم إلى القيام به؛ ولكن هذا لا يعني أنها كانت لديك نية لجعل مترجم تفعل ذلك. وأنا أعلم أنني لست مبرمج arrogent ما يكفي للاعتقاد بأن كل مرة كتابة التعليمات البرمجية يفعل بالضبط ما كنت أحاول أن تجعل من القيام به. بالإضافة إلى ذلك، غالبا ما أجد أنه يساعدني على قبض خطأ منطقي سخيفة في قانون بلدي التي يمر بها بعد لقد كتب عنه ومحاولة لشرح ما كنت أنوي لرمز للقيام به.

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

ونقول لهم لتوثيق وظائفهم واجهات مع commments جافادوك ثم لتشغيل التعليمات البرمجية من خلال Doxygen لتوليد وثائق HTML تبحث باردة لمدوناتها. عامل البرودة يمكن أن يكون حافز جيد في بعض الأحيان.

وأنا استخدم تقنية دقيقة واحدة:

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

إذا المطورين لا تكتب التعليقات، بناء فشل! وبعد ذلك، لديهم لكتابة تعليق، وذلك بعد فترة من الوقت، وأنها تعودت على ذلك.

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

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

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

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

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

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

في رأيي (وأنا أتحدث عن البرمجة. صافي هنا) إذا كان لديك لوضع تعليق كنت قد فشلت في جعل رمز للقراءة. الجواب عادة ريفاكتور!

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

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

وتوظيف فقط المهندسين الجيدين الذين ضمان مدوناتها ينص ضمنيا نية (باستخدام التعليقات وغير ذلك). ولمن يريد وظيفة يجب أن تفعل ذلك الحق. قاسية، ولكن عادلة، IMHO.

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

لا تنتمي إلى StackOverflow