مستند سازی توابع

اگر در کد زدن بتوانید از شیوه استاندار استفاده کرده و مستند سازی را به طور صحیح انجام دهید کد شما راحت تر خوانده و فهمیده میشود , راحت تر رفع اشکال و راحت تر بروزرسانی میشود. یک برنامه یک بار نوشته شده ولی دفعات متعدد خوانده میشود :

• هنگام رفع اشکال $debugging$
• هنگام اضافه کردن قسمتی به برنامه
• هنگام خواندن و فهمیدن برنامه توسط شخص خود یا شخصی دیگر

برای نام گذاری کلاس ها , توابع و متغیر ها نام های با معنی استفاده کنید. خوب است که از قاعده کلی زیر پیروی کنید:

1. نام متغیر ها : با حرف کوچک شروع شده و به هنگام رسیدن به کلمه جدید حرف بزرگ استفاده میشود مانند myVar
2. نام ثابت ها: از حروف بزرگ استفاده شده و به منظور جدا کننده از $'_'$ اسنفاده میکنیم مانند MY_CONST
3. نام کلاس ها : با حرف بزرگ شروع شده و به هنگام رسیدن به کلمه جدید از حرف برزگ استفاده میشود مانند MyClass
4. نام توابع : با حرف کوچک شروع شده و به هنگام رسیدن به کلمه جدید حرف بزرگ استفاده میشود مانند myFunction

قبل از تعریف تابع میتوان یک بلاک توضیح نوشت که فرمت آن را در زیر میبینید که توضیحاتی در مورد خود تابع , پارامتر های آن و خروجی آن در آن موجود است و به کمک نرم افزار های مستند سازی میتوان صفحه $html$ توضیحات تابع را به طور خودکار از روی این بلاک تولید کرد.

/**
    Describtion about the Function here
 
    @param p1 Describtion about first parameter
    @param p2 Describtion about second parameter
    .
    .
    @param pn Descrbtion about n-th parameter
    @return Describtion about return value of function
*/
returnType nameOfFuntion(Type_1 P1,Type_2 P2,...,Type_n Pn){ statements }

به عنوان مثال

documentation.cpp

/**
    Returns the area of a Rectangle with the specified width and height.
 
    @param width The width of the Rectangle.
    @param height The height of the Rectangle.
    @return The area of the Rectangle.
*/
int area(int width,int height){return width*height;}