مستندسازی کدهای #C

یکی از نکات حائز اهمیت در حوزهٔ توسعه نرم افزار، مستندسازی عملیاتی است که برنامه نویس در طول فرآیند کدنویسی انجام داده است، به خوبی می‌دانیم که با گذشت تنها جند ماه از نوشتن یک قطعه کد، فراموشی بسیاری نکات مرتبط با کد نوشته شده، امری رایج و حتی در برخی موارد اجتناب ناپذیر است، همچنین واگذاری ادامه روند توسعه به برنامه نویس دیگر نیز، باعث سردرگمی او در درک کدهای نوشته شده توسط برنامه نویس اول می‌شود. از این رو اهمیت و لزوم مستندسازی امور انجام شده امری بدیهی به نظر می رسد، هرچند همین موضوع بدیهی در روند جاری برنامه نویسان ایرانی بسیار مهجور است!

شیوه های متنوع مستندسازی کد لزوم درنظر گرفتن نکات زیر در این باره را پررنگ تر می سازد

  • مستندسازی باید به گونه ای صورت پذیرد که مختصر و گویای نکات ضروری باشد
  • مستندات می بایست در دسترس برنامه نویس باشد، چه برای مطالعه چه برای اصلاح و بازنگری: پرواضح است که نوشتن متون طولانی در فایل ورد و قرار دادن آن در یکی از پوشه های کامپیوتر در مقابل حالتی که برنامه نویس مستندات خود را لابلای کدها و در حین توسعه نرم افزار قرار می دهد، باعث کاهش سطح دسترس پذیری می باشد
  • مستندات باید متناسب با نیاز مخاطب طراحی شود، همانطور که مستندات کدهای نوشته شده به درد مشتری نهایی نرم افزار نمی خورد، انشاء و نوع نگارش مستندات محصول نیز به درد برنامه نویس نخواهد خورد، به بیان ساده تر نرم افزار نیاز مستندات مختلف از دیاگرام های UML و مستندات کد تا مستندات مشتری است
  • تهیه مستندات می بایست برمبنای اصول استاندارد باشد و نه سلیقه ی افراد

 

در ادامه مطب به چگونگی درج مستندات و توضیحات در کدهای سی شارپ خواهم پرداخت:

مستندات کدهای سی شارپ در قالب تگ های XML ایجاد می شود، تگ های استاندارد درج مستندات به شرح زیر است:

<summary>

توضیحات کلی پیرامون بخش هایی از کد، اعم از کلاس، متد، پراپرتی و… را در داخل این تگ قرار می دهیم، همچنین تگ <remarks> برای درج توضیحات کامل تر مورد استفاده قرار می گیرد، و cref Attribute را برای درج لینک به مستندات، به خصوص برای ابزارهای استخراج و ایجاد مستندات نظیر Sandcastle مورد استفاده قرار می گیرد.

مثال:

/// <summary>DoWork is a method in the TestClass class. 
/// <para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine(System.String)"/> for information about output statements.</para>
/// <seealso cref="TestClass.Main"/>
/// </summary> 
    public static void DoWork(int Int1)
    {
    }

در نمونه کد فوق چگونگی ذکر توضیح کلی عملکرد با استفاده از تگ <summery>، درج لینک راهنما با استفاده از cref را می بینیم.

<para>

توضیحات مرتبط با یک پارامتر را دربردارد، این تگ داخل تگ های <summery>, <remarks>  و یا <returns> قرار می گیرد. (به مثال تگ <summery>  دقت نمایید)

<remarks>

تگ <remarks> حاوی اطلاعات  تکمیلی است، این اطلاعات در پنجره object explorer ویژوال استدیو که ساختار، اعضاء وساختار سلسله مراتبی آبجکت ها را نمایش می دهد، قابل مشاهده است.

/// <summary> 
/// You may have some primary information about this class. 
/// </summary> 
/// <remarks> 
/// You may have some additional information about this class. 
/// </remarks> 
public class TestClass
{
}

<c> و <code>

متنی که در داخل این تگ قرار میدهیم، موقع نمایش راهنمای ویژوال استدیو به صورت کد برنامه نویسی قالب دهی می شود، مثلا: نام کلاس و نام متد در کد زیر با رنگ متفاوت از متن مشخص می شود، به تصویر زیر دقت نمایید:

/// <summary><c>DoWork</c> is a method in the <c>TestClass</c> class. 
        /// </summary> 
        public static void DoWork(int Int1)
        {
        }

Tag_C_Csharp_Commenting

<example>

چگونگی استفاده از یک قطعه کد را در قالب مثال بیان می کند، عموما اینتگ را داخل تگ <code> به کار می بریم

/// <summary> 
        /// The GetZero method. 
        /// </summary> 
        /// <example>  
        /// This sample shows how to call the <see cref="GetZero"/> method.
        /// <code> 
        /// class TestClass  
        /// { 
        ///     static int Main()  
        ///     { 
        ///         return GetZero(); 
        ///     } 
        /// } 
        /// </code> 
        /// </example> 
        public static int GetZero()
        {
            return 0;
        }

 

<list>

این تگ جهت نمایش لیست گونه تعدادی  از نکات در توضیح به کار می رود

/// <summary>Here is an example of a bulleted list: 
        /// <list type="bullet">
        /// <item> 
        /// <description>Item 1.</description> 
        /// </item> 
        /// <item> 
        /// <description>Item 2.</description> 
        /// </item> 
        /// </list> 
        /// </summary> 
       public static void Test()
        {
        }

Tag_List_Csharp_Commenting

<paramref>

هنگامی که قصد درج توضیحاتی پیرامون یک پارمتر را در بین تگ های <summery> و یا <remarks> داشته باشیم، از این تگ بهره می گیریم، بدین صورت نام پارامتر مورد نظر کمی ضخیم تر نمایش داده خواهد شد. نام پارامتر را با name و داخل “” مشخص می سازیم.

/// <summary>DoWork is a method in the TestClass class.   
/// The <paramref name="Int1"/> parameter takes a number.
/// </summary> 
    public static void DoWork(int Int1)
    {
    }

Tag_paramref_Csharp_Commenting

<returns>

جهت درج توضیح پیرامون مقدار خروجی متد به کار می رود

/// <returns>Returns zero.</returns> 
    public static int GetZero()
    {
        return 0;
    }

<typeparamref>

نوع داده ای یک پارامتر را ذکر می نماید، در مبحث Generics که ما در حین نوشتن کد متد و یا کلاس generics از نوع داده ای که بعدن به کار برده خواهد شد اطلاع نداریم، استفاده می شود.

/// <summary> 
    /// Creates a new array of arbitrary type <typeparamref name="T"/>
    /// </summary> 
    /// <typeparam name="T">The element type of the array</typeparam>
    public static T[] mkArray<T>(int n)
    {
        return new T[n];
    }

Tag_typeparamref_Csharp_Commenting

<value>

توضیح مقداری را که یک property عرضه می نماید را بیان می کند، با توضیح کلی property که با تگ <summery> درج می شود تفاوت دارد، در صورتی که کامپایل با استفاده از doc/ انجام شود به عنوان توضیح در فایل مستندات درج می گردد

    /// <summary>The Name property represents the employee's name.</summary> 
    /// <value>The Name property gets/sets the value of the string field, _name.</value> 

    public string Name
    {
        get
        {
            return _name;
        }
        set
        {
            _name = value;
        }
    }

 

<exception>*

اشاره به نوع داده ای خطاهایی دارد که احتمال می رود در روند اجرای کد throw شوند، کامپایلر از وجود چنین نوع داده ای از خطا اطمینان حاصل میکند و توضیحات مرتبط در قابل XML مستندات نیز درج خواهد شد.

 /// <exception cref="System.Exception">Thrown when...</exception>
    public void DoSomething()
    {
        try
        {
        }
        catch (EClass)
        {
        }
    }

<include>*

اشاره به فایل مجزا از سورس کد دارد که توضیحات در آن درج شده، کمک میکند تا افراد به صورت مستقل و جداگانه به تولید کد و یا مستندات کد بپردازند، پارامترها:

  • filename: نام فایل XML که حاوی توضیحات است
  • tagpath: مسیر مرتبط با توضیحات کدی که این تگ را برای آن درج کرده ایم (XPath)
  • name: نامی که برای توضیح درج شده انتخاب شده است (id)
  • id: شاخصه ی id تگی که توضیح را در بر دارد
/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />
class Test
{
    static void Main()
    {
    }
}

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />
class Test2
{
    public void Test()
    {
    }
}

<param>*

درج توضیح برای پارامترها

/// <param name="Int1">Used to indicate status.</param>
    /// <param name="Float1">Used to specify context.</param>
    public static void DoWork(int Int1, float Float1)
    {
    }

<permission>*

اشاره به permissionset ی دارد که دسترسی افراد به کد را مشخص میکند، اینکه چه کسی مجوز دسترسی به کد را دارد یا خیر.

پارامترها:

  • cref: ارجاع به فیلدی که هنگام کامپایل کد فراخوانی می شود، کامپایلر وجود آن را کنترل کرده و آن را به نام مناسب جهت درج المنت XML ترجمه میکند
  • description:
/// <permission cref="System.Security.PermissionSet">Everyone can access this method.</permission>
    public static void Test()
    {
    }

<see>*

درج لینک برای توضیح بهتر در مستندات خروجی گرفته شده، در محیط ویژوال استدیو تنها ضخیم تر نمایش داده می شود ولی در مستندات تولید شده لینک به مورد ذکر شده ایجاد خواهد شد.

/// <summary>DoWork is a method in the TestClass class. 
    /// <para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine(System.String)"/> for information about output statements.</para>
    /// <seealso cref="TestClass.Main"/>
    /// </summary> 
    public static void DoWork(int Int1)
    {
    }

<seealso>*

متنی که قصد داریم در بخش See Also نمایش داده شود (همانند مطالبی که در MSDN می بینیم)

<typeparam>*

در مواردی که از انواع generics استفاده میکنیم، این تگ IntelliSense ویژوال استدیو را وادار به نمایش نوع به کار رفته خواهد کد

/// <summary> 
    /// Creates a new array of arbitrary type <typeparamref name="T"/>
    /// </summary> 
    /// <typeparam name="T">The element type of the array</typeparam>
    public static T[] mkArray<T>(int n)
    {
        return new T[n];
    }

درج < > در توضیحات کد

/// <summary cref="C &lt; T &gt;">
/// </summary>

 

پینوشت1: در صورتیکه توضیحات و مستندات کد به درستی درج گردند، قادر خواهیم بود تا با ابزارهایی نظیر VSDoc مستنداتی شبیه به MSDN تولید نمایینم.

پینوشت2: این امکان وجود دارد تا TFS خود را مقید به کنترل توضیح گذاری صحیح کد برنامه نویسان تیم نماییم.

9 دیدگاه دربارهٔ «مستندسازی کدهای #C;

  1. استاد با تشکر زیاد یه سوال. این اطلاعات دقیقا کجا ذخیره میشه!؟توی خود فایل های dll یا pdb?!
    یعنی اگه جایی از dll های فایل تولید شده استفاده میکنیم صرفا وجود dll ها کافیه تا این اطلاعات به نمایش در بیاد!؟

    پاسخ
  2. سلام؛
    میشه در زمان CheckIn با استفاده از StyleCop نوشتن مستند رو اجباری کرد و در واقع از بارگذاری کدهای بدون مستند(Comment) جلوگیری کرد.

    پاسخ
  3. سلام اقای مصباحی یه خواهش ازتون داشتم میشه لطف کنید و یک کد کوتاه سی شارپ رو مستند سازی کنید و به ایمیلم بفرستید ازتون بسیار سپاسگذارم

    پاسخ
  4. سلام آقای مصباحی میشه راهنمایی کنید که چطوری یک کد سی شارپو به htmlتبدیل کرد…..استادم اول ازم خواست یه کد سی شارپو به xmlتبدیل کنم الان هم خروجی htmlرو میخوان…لدفا سریع جواب منو بدید زمان زیادی ندارم

    پاسخ

دیدگاهتان را بنویسید