راهنمای سبک کدنویسی
گروه بازیسازان - بهمن 1385

هشدار!

مطالبی که در زیر می‌آیند قوانینی هستند که برای استفاده درون گروه بازیسازان وضع شده‌اند. به باور ما، برخی از قوانین برای بهبود و ارتقای تلاشهای برنامه نویسی و ساختار بهتر وضع شده‌اند. اما بسیاری نیز صرفا به این علت وضع شده‌اند که وجود یک استاندارد، بهتر از عدم وجود آن است.

مسلما بسیاری از قواعد سلیقه‌ای هستند، اما حتی اگر این قواعد را دوست ندارید، یا آنها را بیهوده، دست و پا گیر یا نامناسب تلقی می‌کنید، در هنگام همکاری با گروه ملزم به رعایت آنها هستید. در مواقعی که با گروه همکاری نمی‌کنید مسلما می‌توانید هرگونه که مایلید کد بنویسید!

در نهایت اینکه پیشنهادات یا نظرات شما در مورد این قوانین به شدت ارزشمند تلقی می‌شوند؛ پس آنها را ابراز کنید. به طور کلی اعضا موظفند در مطالعه ی اولیه هر سند، حداقل دو پیشنهاد درباره ی آن ارائه دهند.

حقوق سازندگان

تا زمان اخذ تصمیم درباره مجوز سند، کلیه حقوق این سند متعلق به گروه بازیسازان است.

تقدیر از نویسندگان و همیاران

85/11/20 -- نسخه نخست این سند با 5 اصل بنیادین در 7 عنوان توسط سجاد نفیسی نوشته شد.
85/12/7 -- سند با توجه به پیشنهادات احسان طاهری، محمدرضا محمدی و هدایت وطن‌خواه اصلاح شد.

باورهای بنیادین

آنچه در ادامه این بخش می‌آید، چکیده‌ای از باورهایی است که هنگام نوشتن این سند مدنظر بوده است.

این باورها اساس این سند را تشکیل می‌دهند و قواعد سایر بخش‌ها باید از آن‌ها پیروی کنند.

همچنین اگر در حین کار و کدزدن روزمره؛ با موردی مواجه شدید که مشمول هیچ یک از قوانین دیگر این سند نمی‌شد، ضمن آنکه آن نقص را به مسئول سند گزارش می‌کنید، روشی را پیش بگیرید که حداکثر تطابق را با این باورها دارد.

اگر در حال یک مرور سریع هستید می‌توانید این بخش را بیخیال شوید و به بخش‌های بعدی بپردازید.

اصل نخست: کد باید به اندازه متن انگلیسی خوانا باشد، با این تفاوت که کد قابل اجرا شدن است!
1. بنا به اصل نخست، طول ساختارها باید حداقل نگهداشته شود.
2. بنا به اصل نخست، کد باید دارای سطحی از «تجرد» باشد که خوانایی آن نزدیک به زبان طبیعی شود.
اصل دوم: یک سبک خوب، بین پراکندگی و فشردگی تعادل برقرار می‌کند تا خوانایی حداکثر شود.
1. فشردگی بالا کد را ناخوانا می‌کند. سی++ قابلیت خارق العاده‌ای در فشرده نویسی دارد که باید کنترل شود. نام بیش از حد مختصر متغیرها، فاصله نگذاشتن و به هم چسباندن واحدهای مختلف منطقی فشردگی را افزایش می‌دهند.
2. پراکندگی عمودی یا افقی باعث افزایش فضای خالی یا بی معنا می‌شود که خوانایی را کاهش می‌دهد. نام بیش از حد طولانی برای متغیرها، فاصله گذاری بیش از حد افقی یا عمودی و مواردی از این دست باید کنترل شوند.
اصل سوم: ساختار ظاهری کد باید به ساختار منطقی نزدیک باشد. چیزهای مربوط به هم باید در یک رده ظاهری قرار گیرند.
- بنا به اصل سوم، ساختارها باید در کد واضح باشند.
- بنا به اصل سوم، ساختارها باید ظاهری مرتبط با کار خود داشته باشند.
اصل چهارم: همسان بودن کد در رسانه‌های مختلف و حفظ ظاهر آن در همه جا یک اصل است.
- بنا به اصل چهارم، کد باید روی چاپگر قابل چاپ باشد، بدون شکستگی و پراکندگی.
- بنا به اصل چهارم، استفاده از کاراکترهایی که در مکانهای مختلف متفاوت دیده می‌شوند ممنوع است.
اصل پنجم: سبک کدنویسی باید در حد توان در خدمت کدنویسی دقیقتر و سریعتر باشد.

ساختار فایل

هر فایل با این کامنت استاندارد آغاز می‌شود. (به جای نام فایل و سال مربوطه اطلاعات صحیح وارد شود)

ساختار کلی درون فایل

ساختار کلی

نخست کلاس‌های Exception و سپس کلاس‌های اینترفیس و در نهایت کلاس‌های عادی می آیند.

تورفتگی و طول سطر

بند 1: تورفتگی ساختار‌های کنترلی با 4 کاراکتر فاصله انجام می‌شود. (از tab استفاده نکنید)
بند 2: حداکثر 80 ستون کاراکتر مجاز است. خطوط طولانی در محل مناسب می‌شکنند و با یک نیم‌تورفتگی اضافی دنبال می‌شوند. می‌خواهیم مطمئن شویم که کد به سادگی قابل چاپ شدن روی کاغذ است، و روی نمایشگر نیز بدون اسکرول کردن سطر به تمامی دیده می‌شود. همچنین این کار مانع از ایجاد کدهای طولانی و تو در تو می‌شود.
بند 3: وقتی یک سطر می‌شکند، با یک نیم‌تورفتگی با 2 کاراکتر فاصله در سطرهای بعدی دنبال می‌شود.

کلاس/رکورد

ترتیب اعضای کلاس (توابع و متغیرها)

کلاس یا رکورد به سه بخش اصلی تقسیم می‌شوند که همیشه ظاهر نمی‌شوند، و محدودیتهایی نیز دارند. اما اگر هر تعداد از این بخش‌ها وجود داشته باشد، آنها را به این ترتیب می‌آوریم:
1. public
2. protected
3. private
درون بخش‌های اصلی، اعضای کلاس در دسته بندی‌هایی برحسب نوعشان و به ترتیب زیر قرار می‌گیرند:
1. متغیرهای const static
2. انواع داده ای تعریف شده درون کلاس. حتی‌الامکان با ترتیب زیر:
  1. typedef
  2. enum
  3. struct
  4. class
3. فیلدها
4. سازنده‌ها
5. مخرب
6. متدها
تبصره: در موارد ضروری، امکان تعریف متغیرهای const static بعد از تعاریف نوع وجود دارد.
درون هریک از دسته‌های بالا، اعضا ترتیب الفبایی دارند.

توابع عضو

اعلان تابع در هدر (.h)

شکستن:
هنگامی‌که تعداد پارامترها بالا می‌رود، آنها را در محل مناسب (بعد از کاما) بشکنید و در سطور بعدی یک نیم‌تورفتگی ایجاد کنید.
```
int myMethod(int x, int y, int z, double a, 
  double b)
{
}
```

تعریف تابع در فایل کد (.cpp)

بین دو تابع، یک سطر خالی قرار دهید.
آکولادها: آکولاد‌های باز و بسته متدها و توابع در سطر جدید نوشته می‌شوند.
```
int myMethod(
  int x)
{
}
```
در فایل کد، هر پ
ارامتر را با اعمال نیم‌تورفتگی در یک سطر بنویسید.
```
int myMethod(
  int    x,
  int    y, 
  int    z, 
  double a, 
  double b)
{
}
```

ساختار درون تابع

ساختار:

هر متغیر را در یک سطر جدا تعریف کنید و از تعریف همزمان دو متغیر پرهیز کنید. این روش کامنت زدن برای متغیرها را تشویق می‌کند.
یک سطر خالی بین تعریف متغیر‌ها و کد تابع قرار دهید.
- تبصره: توابع کوتاهتر از 6 خط (با احتساب تعریف متغیرها) از این قاعده مستثنی هستند.
پیشنهاد: به منظور افزایش خوانایی؛ ترجیحا تعریف متغیرها را در ابتدای هر بلاک کد انجام دهید. تعریف را تا زمان اولین استفاده به تعویق نیاندازید.

int fooFunction(int foo1, int foo2)
{
    int first = 0;  // محل مناسب تعریف متغیر - ابتدای تابع
    ...
    if (foo1 < foo2) {
        int tmp = foo1; // محل مناسب تعریف متغیر - ابتدای بلاک شرطی
        foo1 = foo2;
        foo2 = tmp;
    }
    ...
    int a = 100;  // محل نامناسب
    ...
}

سبک عبارات:

پیشنهاد: با گذاشتن پرانتز، روی اولویت عملگر‌ها تاکید کنید.
به جز برای عملگرهای تک عملوندی و عملگرهای اصلی حسابی و منطقی (+,-,*,/,<,>,==,!=,<=,>=,&&,||) اولویت سایر عملگرها بهتر است با پرانتز معین شود؛ چون ممکن است خواننده به خوبی شما با اولویت‌ها آشنا نباشد.

فاصله گذاری افقی:

تمام عملگرهای یکتایی بدون هیچ فاصله‌ای به عملوند خود می‌چسبند. (مانند: ++,--,-,!,* و ...)
تمام عملگر‌های دوتایی و سه تایی، باید حداقل یک فاصله قبل و یک فاصله بعد از خود داشته باشند.
تبصره: برای کاما (,) تنها یک فاصله بعد از آن قرار دهید. قبل از آن فاصله نگذارید.
تبصره: پرانتز و کروشه با محتویات داخل خود فاصله ندارند. (فاصله بعد از عملگر باز و قبل از عملگر بسته قرار نمی‌گیرد)
تبصره: عملگرهای (.)، (::) و (->) قبل و بعد از خود فاصله ندارند.

تراز عمودی:

در مکانهایی که مناسب می‌بینید، می‌توانید سطور مختلف کد را هم‌تراز کنید، به شرطی که باعث به هم ریختگی یا بد ریختی کد نشود.
توجه: هم‌تراز کردن عمودی در مکانهایی اجازه داده می‌شود که فاصله گذاری افقی اجازه قراردادن بیش از یک فاصله را داده است.
```
int first  = b;
int last   = a;
int middle = (a + b) / 2;
x = a * b +
    c * d +
    e * f;
```

فراخوانی تابع:

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

بین نام تابع و پرانتزها فاصله نگذارید.

{ درست }  createFoo(myChar, 0, 1);
{اشتباه}  createFoo(myChar,0,1);
{اشتباه}  createFoo( myChar, 0, 1 );
{اشتباه}  createFoo ();

براکت: درون براکت فاصله نگذارید.

{ درست }  x = dataArray[index];
{اشتباه}  x = dataArray[ index ];

قوانین دستورات کنترلی

آکولادهای دستورات کنترلی: آکولاد باز برای دستورات کنترلی با یک فاصله در انتهای همان دستور ظاهر می‌شود. آکولاد بسته سطر مخصوص خود را دارد.
```
if (x == y) {
}
else {
}
```

بند: بین دستورات کنترلی و پرانتزها یک فاصله قرار دهید.
بند: قبل و بعد از هر عملگر مقایسه‌ای یک فاصله قرار دهید.
```
{ درست }  while (x == y)
{اشتباه}  while(x == y)
{اشتباه}  while (x==y)
```

بلاک switch

switch ساده: سطر خالی بین case‌ها وجود ندارد. شامل:

case تک خطی:
به همراه break، تماما در یک خط نوشته می‌شود و شامل یک یا دو دستور کوتاه است.

switch (stateNo) {
case 1: one small command; break;
// محل کامنت که قاعدتا یا برای همه کیسها  قرار می‌گیرد یا برای هیچکدام
case 2: one small command; break;
default: one small command; break;
}

switch حجیم: یک سطر خالی قبل از هر case دارد. شامل:
- case چند خطی:
  استفاده از بلاک ساده (غیر کنترلی) درون case‌ها مطلقا ممنوع است.
  تعریف متغیر درون switch مطلقا ممنوع است. در صورت نیاز تابع بنویسید!
  تورفتگی break با کد درون case یکسان است.

کامنت گذاری: در صورت نیاز، کامنت مربوط به هر case در یک سطر مخصوص به خود و درست ماقبل دستور case قرار می‌گیرد. (هر نوع کامنتی مجاز نیست، به راهنمای توضیحات درون کد مراجعه کنید!)

switch (stateNo) {

case 2: 
    case with one significantly long command; 
    break;
  
// محل کامنت که قاعدتا یا برای همه کیسها  قرار می‌گیرد یا برای هیچکدام
case 3:
    ...
    case with multiple commands must be in braces;
    ...
    break;
  
default:
    a command;
    break;
}

بلاک do..while

دستور do..while با بقیه دستورات متفاوت است، اما ظاهر آن از همان قانون پیروی می‌کند.
```
do {
    ...
}
while (!found);
```

بلاک for

در دستور for، قبل و بعد از هر سمی‌کالن یک فاصله می‌آید. قبل از سمی‌کالن فاصله نداریم.
```
for (int i=0 ; i < items.count() ; ++i) {
    ...
}
```