گفتگوی فنی شماره یک - اصول و قواعد کد نویسی

[علیرضا مداح]

حوب ابتدا از تاخیر به وجود آمده پوزش می خواهم، سعی می کنیم که از این به بعد بحث با سرعت مناسبی پیگیری شود،
شروع می کنیم،
بهره گیری از ابزار ارزشمند StylCop را به تمامی برنامه نویسان پیشنهاد می کنم، مطمئن باشید به محض شروع کار با آن، انقلابی در کدهای شما رخ خواهد داد، همه چیز مرتب، منظم، سر جای خود!
یکی از بخش هایی هم که StyleCop بر روی آن تمرکز دارد، همین مستندات است،
در پست قبلی آقای موسوی اشاره ای به XML Documentation داشتند،
شما می توانید هنگام مستندسازی کدهای خود، از ویژگی Inline XML Code Documentation بهره بگیرید، به زبان ساده تر، داخل کد، مستندان آن را به زبان XML و با یک ساختار مشخص می نویسید، این شاختار مشخص از یکسری Tag هایی تشکیل می شود، پس از اینکه کد خود را مستند نمودید، هر موقع که توسعه گر دیگر قصد استفاده از آن را داشته باشد، Intellisense به کمک او خواهد آمد و بنا بر ساختاری که شما برای آن تعریف نمودید، آن شخص می تواند از عملکرد آن آگاه شود، همچنین ابزارهایی وجود دارد که مستندات XML موجود در کد را در یکسری قالب های مشخص برای شما اسخراج می نماید تا به طور مثال بتوانید مستندات Class Library که تهیه نمودید را به صورت مجزا توزیع نمایید،
در مثال آقای موسوی شما متوجه شدید که هر زمان، قبل از یک متد، کلاس، پروپرتی یا هر عضو دیگری. سه بار کلید / را بزنید، یک قالب از پیش تعیین شده همراه با یکسری Tag ها برای شما تولید خواهد شد، این قالب بستگی به عضوی دارد که قصد مستندسازی آن را دارید، طبیعتا" هر کدام از این Tag ها ممکن است برای عضو های مشخص قابل استفاده باشد،
خوب فرض کنید می خواهیم یک متد را مستند کنیم، به چه اطلاعاتی در رابطه با آن نیاز داریم؟ یا به عبارتی کدام یک از بخش های آن را می توانیم مستند کنیم؟

• خلاصه ای از عملکرد آن(summary Tag)
• توضیح پارامترهای آن(param Tag)
• Exception هایی که ممکن است هنگام استفاده از این مند رخ دهد(exception Tag)
• توضیح مقدار بازگشتی متد(returns Tag)
• توضیحات بیشتر در مورد نحوه عملکرد و نکاتی که در استفاده از آن باید مد نظر قرار داد(remarks Tag)
• ارائه ی مثالی جهت کار با آن متد(example Tag)
• معرفی مطلب مرتبط با مستندات این متد که دیدن آن مفید است(seaalso tag)
• ...
• تمامی Tag ها در MSDN به تفصیل بررسی شده اند،

می خواهیم بخشی از مستنداتی که برای متد System.Decimal.Multiply(Decimal, Decimal) نوشته شده است را بررسی نماییم:

        /// <summary>

        /// Multiplies two specified System.Decimal values.

        /// </summary>

        /// <param name="d1"> A System.Decimal (the multiplicand).</param>

        /// <param name="d2"> A System.Decimal (the multiplier).</param>

        /// <returns>A System.Decimal that is the result of multiplying d1 and d2.</returns>

        /// <exception cref="System.OverflowException">The return value is less than System.Decimal.MinValue or greater than System.Decimal.MaxValue.</exception>

        public static int Multiply(decimal d1, decimal d2)

        {

            // Implementaion goes here...

        }

در اینجا جزئیات پیاده سازی مد نظر ما نیست،
همانطور که مشاهده می کنید در داخل تگ <summary>عملکرد متد به طور خلاصه تشریح شده است، هر یک از پارامترها نیز توسط تگ <param> توصیف شده اند و در داخل تگ <returns> نیز در مورد مقدار بازگشتی متد اطلاعاتی به ما داده شده است، به کاربرد تگ <exception> دقت کنید، در element این تگ که cref نام دارد، Exception آورده شده است و در قسمت توضیحات هم دلیل وقوع آن توضیح داده شده است، همانطور که مشاهده می کنید این Exception زمانی رخ می دهد که "مقدار بازگشتی کمتر از System.Decimal.MinValue یا بیشتر از System.Decimal.MaxValue باشد."
پس تا اینجا کمی با XML Documentation آشنا شدیم، خوشحال خواهم شد که توضیحات آقای موسوی را هم در این مورد بشنویم تا سپس به بررسی چگونگی استخراج مستندات XML از داخل کد بپردازیم،/

[mehdi.mousavi]

واقعیت اینه که در این زمینه حرف قابل عرضی باقی نمونده... البته فقط یک نکته به ذهنم میرسه و اونم تولید ماشینی این Comment هاست. تصور کنید ابزاری داشته باشید که توسط اون بتونید کلاس، متود، Property و ... رو در برنامه Comment کنید. طبیعتا این Comment کردن نمیتونه بسیار هوشمندانه باشه، چون ماشین حقیقتا نمیدونه کارکرد یک متود چیست و چه هدفی رو دنبال میکنه که بخواد توضیح مناسبی برای اون ارائه کنه. اما میتونه بنیان مورد نیاز شما رو برای نوشتن Comment ها محیا کنه.

خوشبختانه سالهای قبل، چنین ابزاری طراحی شد و بصورت رایگان در اختیار عموم قرار گرفت. نام این ابزار GhostDoc هستش و به شما کمک میکنه تا به بخشهای مورد نظر در برنامه Comment بیفزایید. GhostDoc تقریبا 13 ماه پیش توسط شرکت SubMain خریداری شد اما خوشبختانه کماکان بصورت رایگان عرضه میشه. برای دریافت اون میتونید به این آدرس رجوع کنید.

پس از نصب GhostDoc (که حدودا 930KB حجم داره)، آیتم جدیدی تحت عنوان GhostDoc به منوی Tools اضافه میشه. پس از نصب برنامه و هنگامیکه Visual Studio رو باز میکنید، میتونید برای اولین بار اونو Config کنید (بطور مثال کلیدی تعیین کنید که هنگام زدن اون کلید، Comment مورد نظر روی تابع انتخاب شده نوشته بشه).

کلاس Porsche رو مجددا مثال میزنم، اما اینبار Comment هایی که در این کلاس میبینید توسط GhostDoc ایجاد شده و من توش دست نبردم:

/// <summary>

/// 

/// </summary>

public class Porsche : Car

{

    /// <summary>

    /// Initializes a new instance of the <see cref="Porsche"/> class.

    /// </summary>

    /// <param name="brand">The brand.</param>

    /// <param name="color">The color.</param>

    public Porsche(string brand, System.Drawing.Color color)

        : base(brand, color)

    {

    }



    /// <summary>

    /// Initializes a new instance of the <see cref="Porsche"/> class.

    /// </summary>

    /// <param name="brand">The brand.</param>

    public Porsche(string brand)

        : this(brand, System.Drawing.Color.Empty)

    {

    }



    /// <summary>

    /// Initializes a new instance of the <see cref="Porsche"/> class.

    /// </summary>

    public Porsche()

    {

    }

}

البته شما باید حتما Comment نوشته شده رو بدقت بررسی کنید و تغییرات مقتضی رو در اون اعمال کنید، چون همونطور که عنوان کردم، این Comment ها توسط ماشین تولید میشه و طبیعتا دقیق نیست؛ اما میتونه کمک بسزایی در سرعت بخشیدن به نوشتن Comment ها داشته باشه.

با این توضیحات، اکنون میتونیم به کاربرد دیگه این Comment ها اشاره کنیم. جناب مداح؟