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

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

حوب ابتدا از تاخیر به وجود آمده پوزش می خواهم، سعی می کنیم که از این به بعد بحث با سرعت مناسبی پیگیری شود،
شروع می کنیم،
بهره گیری از ابزار ارزشمند 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 از داخل کد بپردازیم،/