XML وتعليقا نصائح C# البرمجة [مغلقة]

Question

صباح الخير, مساء الخير مساء أو ليلا (حسب التوقيت).

هذا هو مجرد سؤال عام حول XML معلقا في C#.لم أكن كبيرة جدا في التعليق برامج بلدي, لقد كنت دائما أكثر من مطول متغير/الممتلكات/طريقة المنادي وترك مدونة تتحدث عن نفسها.أنا لا أكتب تعليقات إذا أنا الترميز شيئا مربكا إلى حد ما, ولكن بالنسبة للجزء الأكبر لا أكتب الكثير من التعليقات.

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

سؤالي هو عن المعايير والاتفاقيات الدولية.هل هناك دليل على "جيد" XML التعليق?يجب تعليق كل متغير و الممتلكات ؟ كل طريقة ؟ أنا في الأساس تبحث عن نصائح حول كيفية كتابة تعليقات جيدة من شأنها أن تكون جمعتها الرمال في وثائق جيدة جدا مبرمجين آخرين لا تلعن اسمي عندما تنتهي الحاجة إلى العمل على قانون بلدي.

شكرا لكم مقدما على النصائح والاقتراحات ، سكوت Vercuski

Answer 1

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

لا ننسى أن هناك أدوات تجعلك XML وتعليقا المهام أسهل:

• GhostDoc - التعليق الميراث و النموذجيه الإضافية.
• Sandcastle ملف المساعدة باني - التعديلات الرمال المشاريع عبر واجهة المستخدم الرسومية ، يمكن تشغيلها من سطر الأوامر (على بناء التشغيل الآلي), و يمكن تحرير MAML للمساعدة مواضيع لا المستمدة من التعليمات البرمجية.(إن 1.8.0.0 ألفا النسخة مستقرة جدا جدا تحسنت.وقد تم استخدامه لمدة شهر تقريبا الآن أكثر من 1.7.0.0)

Answer 2

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

XML تعليقات كبيرة API التنمية.أنها تعمل بشكل جيد مع Intellisens وأنها يمكن أن يكون لك توليد تعليمات HTML الوثيقة في أي وقت من الأوقات.

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

حسنا بما أنها مكلفة للحفاظ على ، لأن الكثير من غير رموز خاصة (في غير API التنمية) تستخدم فقط 1 أو 2 فئات و منذ هذه symboles غالبا ما تفسر نفسها بنفسها ، لن ينفذ قاعدة تقول أن كل غير خاص الرمز يجب أن يكون XML علق. هذا من شأنه أن يكون مبالغة و conterproductive.ما سوف تحصل عليه هو ما رأيته في الكثير من الأماكن :فارغة تقريبا XML التعليقات إضافة شيء إلى symbole اسم.ورمز هذا هو فقط أقل قليلا للقراءة...

أعتقد أن جدا جدا المهم خط دليل حول تعليقات في العادي (غير API) رمز لا ينبغي أن يكون حول وكيف ينبغي أن تكون مكتوبة ولكن عن ما ينبغي أن تحتوي على.الكثير من المطورين لا تزال لا تعرف ما إلى الكتابة.وصف ما ينبغي أن يكون علق ، مع أمثلة الأفضل للحصول على التعليمات البرمجية الخاصة بك من عادي :"هل استخدام XML التعليقات على كل غير خاصة symbole.".

Answer 3

وأنا توثيق الطبقات العامة والجمهور / أعضاء المحمي من تلك الفئات.

وأنا لا توثيق أعضاء من القطاع الخاص أو الداخلي أو الطبقات الداخلية. المتغيرات بالتالي (أعتقد تقصد الحقول) لأنها الخاص.

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

والسعي إلى وضع بعض الأمثلة حيث استخدام ليست واضحة.

Answer 4

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

وعموما أنا أحاول جاهدا لإضافة تعليقات مفيدة لجميع أعضاء العام / المحمية، وهو مفيد، لأنه إذا قمت بتشغيل التعليقات أكس خلال بناء، وتحصل على تحذيرات التلقائي للتعليق في عداد المفقودين. اعتمادا على تعقيد، وأنا قد لا ملء كل التفاصيل - أي إذا هو 100٪ واضح ما كل معلمة <م> قد القيام به (أي لا يوجد أي منطق خاص، وهناك فقط 1 طريقة منطقية لتفسير المتغيرات)، ثم I قد الحصول على كسول وليس إضافة تعليقات حول المعلمات.

ولكن أنا بالتأكيد محاولة لوصف ما الأساليب وأنواع وخصائص وغيرها تمثل / القيام به.

Answer 5

ونحن توثيق الأساليب العامة / خصائص / الخ في مكتباتنا. كجزء من عملية الإنشاء نستخدم NDoc لإنشاء مرجع ويب MSDN الشبيهة. انها كانت مفيدة جدا للإشارة سريعة والبحث.

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

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

Answer 6

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