XML التعليقات: لاستخدام أو عدم استخدام؟

Question

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

وشكرا!

Answer 1

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

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

Answer 2

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

Linker.Extract(IpoValidator validator, MeanDexIndicator Indicator)

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

 <Summary>Extracts The Fumble <\Summary>

هل مضيعة للطاقة. ما يلي هو أفضل:

 <Summary>
 The Fumble needs to be extracted before the bopper can be used. In order for 
 extraction to work a validator and indicator need to be provided. Once extracted 
 the bopper is available in the property Linker.Bopper. On fail this 
 method will raise the CrappedOutException.
 </Summary>

وانظر الفرق؟

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

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

Answer 3

وتعليقات XML هي مفيدة حقا للواجهات برمجة التطبيقات حتى تلك المستخدمة في مجموعة صغيرة.

Answer 4

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

Answer 5

وكما تواجه بقدر داخليا رمز والتعليقات، هنا وظيفة من جانب جيفري باليرمو أنني قرأت للتو ويجب أن نتفق مع.

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

Answer 6

وليس هناك علامة الشرح أن يتم تجاهل وظيفيا ولكن يمكن معالجتها من قبل بعض XSLT إلى أن تتحول مباشرة إلى الوثائق؟ تعليقات جيدة (وأنا استخدامها) ولكن أعتقد أن قيمة العلامة الشرح والمحولة المباشر يمكن أن تفعله تفوق استخدام التعليق وثائق. هكذا وباختصار، والعلامات استخدام الشرح للتوثيق أن يتم قراءتها من قبل الآخرين، واستخدام تعليق ل الملاحظات على نفسك أو "وراء الكواليس" الاشياء (أي، "OMG لإصلاح هذه BEFORE THE WORLD ينفجر! ')