وثائق التعليمات البرمجية:كم هو أكثر من اللازم ؟

Question

كم رمز المستندات الخاصة بك .صافي المصدر هو أكثر من اللازم ؟

بعض المعلومات:لقد ورثت كبيرة تعليمات البرمجة الأساسية التي تحدثت عنها بعض الأسئلة الأخرى لقد نشرت هنا على ذلك.واحدة من "ميزات" هذا برنامج هو الله صف واحد ثابت الدرجة مع >3000 خطوط من التعليمات البرمجية التي تشمل عدة عشرات من أساليب ثابتة.انها كل شيء من Utilities.CalculateFYBasedOnMonth() إلى Utilities.GetSharePointUserInfo() إلى Utilities.IsUserIE6().كل شيء جيد البرمجية التي لا تحتاج إلى أن تكون إعادة كتابة, فقط بتعميل الترميز إلى مجموعة مناسبة من المكتبات.لدي هذا المخطط لها.

لأن هذه الأساليب هي تتحرك إلى طبقة رجال الأعمال ، دور في هذا المشروع هو إعداد نظام صيانة من قبل مطورين آخرين ، أنا أفكر الصلبة وثائق التعليمات البرمجية.في حين أن هذه الأساليب جميع تعليقات مضمنة ، لا يكون جيد (أو أي) رمز المعروف في شكل XML التعليقات.باستخدام مزيج من GhostDoc و الرمال (أو وثيقة X), أنا يمكن أن تخلق بعض جميل وثائق HTML وبعد ذلك إلى SharePoint ، والتي من شأنها أن تتيح للمطورين فهم المزيد عن ما يفعل دون الحاجة إلى التنقل خلال التعليمات البرمجية نفسها.

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

هذه الأمثلة هي من الوثيقة X عينة:

        /// <summary>
        /// Adds a new %Customer:CustomersLibrary.Customer% to the collection.
        /// </summary>
        /// <returns>A new Customer instance that represents the new customer.</returns>
        /// <example>
        ///     The following example demonstrates adding a new customer to the customers
        ///     collection. 
        ///     <code lang="CS" title="Example">
        /// CustomersLibrary.Customer newCustomer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith");
        ///     </code>
        ///     <code lang="VB" title="Example">
        /// Dim newCustomer As CustomersLibrary.Customer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith")
        ///     </code>
        /// </example>
        /// <seealso cref="Remove">Remove Method</seealso>
        /// <param name="Title">The customers title.</param>
        /// <param name="FirstName">The customers first name.</param>
        /// <param name="MiddleInitial">The customers middle initial.</param>
        /// <param name="LastName">The customers last name.</param>
        public Customer Add(Title Title, string FirstName, string MiddleInitial, string LastName)
        {
            // create new customer instance
            Customer newCust = new Customer(Title, FirstName, MiddleInitial, LastName);

            // add to internal collection
            mItems.Add(newCust);

            // return ref to new customer instance
            return newCust;
        }

و:

    /// <summary>
    /// Returns the number of %Customer:CustomersLibrary.Customer% instances in the collection.
    /// </summary>
    /// <value>
    /// An Int value that specifies the number of Customer instances within the
    /// collection.
    /// </value>
    public int Count
    {
        get 
        {
            return mItems.Count;
        }
    }

لذلك أنا أتساءل من أنت:هل الوثيقة كل من التعليمات البرمجية الخاصة بك مع XML التعليقات مع الهدف من استخدام شيء من هذا القبيل NDoc (RIP) أو الرمال?إذا لم يكن كذلك ، كيف يمكنك أن تقرر ما يحصل الوثائق وما لا ؟ شيء مثل API سوف يكون من الواضح المعروف ولكن ماذا عن تعليمات البرمجة الأساسية التي أنت ذاهب لتسليم فريق آخر إلى المحافظة ؟

ماذا ينبغي علي أن أفعل ؟

Answer 1

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

باستخدام تنسيق XML التعليقات هو اختياري.يمكنك استخدام DOxygen أو الأدوات الأخرى التي تعترف صيغ مختلفة.أو الكتابة الخاصة بك الوثيقة مستخرج -- انها ليست صعبة كما قد تظن القيام بعمل معقولة و هي تجربة جيدة.

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

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

Answer 2

لا أحد ذكر الكود الخاص بك لا تحتاج إلى أن تكون منتفخة ، وثائق XML يمكن أن يكون في آخر الملف:

/// <include file="Documentation/XML/YourClass.xml" path="//documentation/members[@name='YourClass']/*"/>

ومن ثم إضافة طريقة يمكن أن تحتوي على أي إضافية XML/التعليقات أعلاه أو إذا كنت تفضل فقط ملخص (كما أن دمج مع ملف منفصل).

إنها أقوى بكثير من القمامة شكل جافادوك ومشتقاتها تجد في PHP/جافا سكريبت (على الرغم من جافادوك مهدت الطريق XML الجملة).بالإضافة إلى الأدوات المتاحة هي أعلى بكثير الافتراضية تبدو من مستندات مساعدة هو أكثر قابلية للقراءة و أسهل لتخصيص (أستطيع أن أقول أنه من بعد أن كتب doclets ومقارنة هذه العملية الرمال/DocProject/NDoc).

Answer 3

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

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

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

Answer 4

جيف لديه حقا مقالة جيدة عن التعليق (أو ينبغي أن أقول ، لا تعليقا) هنا...

http://www.codinghorror.com/blog/archives/001150.html

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

Answer 5

أنا أميل إلى الوثيقة جميع الطرق العامة في المدونة ؛ باستخدام GhostDoc يجعل هذا تافهة.ومن أجل الحد من الفوضى عند تعديل التعليمات البرمجية المصدر ، عموما أنا مجرد انهيار التعليقات عن طريق الذهاب أولا إلى "مخطط الوضعية" (أياستخدام Visual Studio مخطط > انهيار التعاريف الأمر).

لقد حاولت أبدا الرمال, ولكن أنا حقا نقدر الراحة التي توفرها التحسس عن أساليب لدي XML-علق.

Answer 6

أنا دائما تختار XML / جافادوك شكل تعليقات, لأنني أحب أن أكون قادرا على تصفح وثائق API في المعقول شكل (HTML عادة).

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

Answer 7

لا تكرر نفسك.

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

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

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

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

أنا لا تريد أن ترى:"يعود الكونت" عن طريقة اسمه العد.

Answer 8

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

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

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

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

انها عادة ما تكون الأفضل أن يخطئ على جانب من التعليقات إذا كان عليك التأكد من أنها دقيقة.غير دقيقة و/أو unmaintainable التعليقات هي أسوأ لا توجد تعليقات

حتى تطبيق هذه القواعد:

في المثال الأول:"// إنشاء عميل جديد مثيل" هي زائدة عن الحاجة.رمز هو واضح وضوح الشمس.التعليقات الأخرى هي مثالية.فهي توضح ما هو رمز التشغيل على/ما هي resuls

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

Answer 9

أجريت مؤخرا دراسة تبين أن إذا كان لديك مهمة "توجيهات "مثل المتصل يجب أن تفعل X" في الكثير من المواصفات (على سبيل المثال ، "هذا الأسلوب لا X مما يعني Y و Z") ، وهناك خطر كبير جدا أن القراء سوف يغيب التوجيهات.في الواقع ، عندما يرون طويلة وثائق تخطي القراءة alltogether.

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

Answer 10

كل هذا يتوقف على المعايير الخاصة بك ، ولكن بالنسبة لي طاقم ونحن الوثيقة في الجزء العلوي من كل وظيفة في المثال الثاني (وهو بالمناسبة يمكنك القيام به في Visual Studio 2008 من خلال ضرب "/" مفتاح 3 مرات في صف واحد في الجزء العلوي من أي sub أو function!!).

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

Answer 11

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

Answer 12

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

Answer 13

ما كنت قد أظهرت الكثير جدا.لا لنفسك معروفا و حذفه!

رمز يجب أولا أن النفس توثيق من خلال فرض أسلوب المعلمة أسماء.في المثال لديك هو مبين ؛

العملاء العام إضافة(العنوان العنوان, string FirstName, سلسلة MiddleInitial ، سلسلة LastName) هو المفهوم تماما أن القصد من ما يحدث ، كما هو "الكونت".

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

Answer 14

بالمناسبة, وفقا ل "كود نظيفة" (كتاب عظيم ، راجع للشغل) ، ينبغي للمرء تجنب استخدام HTML/XML هوامش الربح خلال التعليقات المضمنة في التعليمات البرمجية المصدر.حتى لو IDE الخاص بك يمكن إنشاء أنيق الوثائق عندما كنت تحوم ، يعتبر تشتيت للغاية وغير قابل للقراءة عند مجرد تصفح المصادر الخاصة بك.