18 روش کاربردی برای خوانایی کدها در برنامه نویسی

خوانایی کد، نقش خیلی مهمی در بحث توسعه و پیشرفت برنامه ها دارد.

از آنجایی که خوانا بودن کد ها یک موضوع گسترده محسوب می شود، ارزش این را دارد که هنگام انجام پروژه بصورت تکی و یا تیمی و حتی زمانی که با پروژه های متن باز یا اوپن سورس سروکار دارید، بیشتر به آن فکر کنید و برای یادگیری و انجام آن وقت بگذارید. در ادامه قرار است 18 روش مهم و کاربردی را برای بالابردن خوانایی کدها بیاموزیم.

1. طریقه کامنت گذاری و مستند سازی کدها

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

مثال زیر را در نظر داشته باشید:

در کد بالا یک خط بعد از تعریف تابع function جوری کامنت گذاری شده که هر زمان در هر جایی از کد تابع function وارد شود، بطور خودکار آن کامنت در خط بعد از آن نمایش داده شود.

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

کامنت های موجود در مثال های ذکر شده مبتنی بر PHPDoc هستند که در محیط توسعه بصورت یکپارچه ی visual studio code نوشته شده اند.

2. تورفتگی یکپارچه کدها برای خوانایی بیشتر

فاصله گذاری و تورفتگی تاثیر زیادی در ظاهر و خوانایی کدها دارد. بهتر است که یک سبک تورفتگی ثابت انتخاب کنید و فقط از همان سبک در تمام کد هایتان استفاده کنید.

استایل و روش های مختلفی برای ایجاد و فرم دهی تورفتگی ها وجود دارد:

مدل 1:

function foo() {
    if ($maybe) {
        do_it_now();
        again();
    } else {
        abort_mission();
    }
    finalize();
}

مدل 2:

function foo()
{
    if ($maybe)
    {
        do_it_now();
        again();
    }
    else
    {
        abort_mission();
    }
    finalize();
}

مدل 3:

function foo()
{   if ($maybe)
    {   do_it_now();
        again();
    }
    else
    {   abort_mission();
    }
    finalize();
}

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

مانند استایل گلابی (PEAR) :

function foo()
{                     // placed on the next line
    if ($maybe) {     // placed on the same line
        do_it_now();
        again();
    } else {
        abort_mission();
    }
    finalize();
}

3. خودداری از ایجاد کامنت طولانی در کدها

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

به مثال زیر توجه کنید:

// get the country code
$country_code = get_country_code($_SERVER['REMOTE_ADDR']);


// if country code is US
if ($country_code == 'US') {


    // display the form input for state
    echo form_input_state();
}

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

// display state selection for US users
$country_code = get_country_code($_SERVER['REMOTE_ADDR']);
if ($country_code == 'US') {
    echo form_input_state();
}

4. گروه بندی کدها برای خوانایی بیشتر

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

به مثال زیر توجه کنید:

// get list of forums
$forums = array();
$r = mysql_query("SELECT id, name, description FROM forums");
while ($d = mysql_fetch_assoc($r)) {
    $forums []= $d;
}
 
// load the templates
load_template('header');
load_template('forum_list',$forums);
load_template('footer');

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

5. نامگذاری به صورت یک مدل ثابت

اگر به قطعه کد زیر توجه کنید متوجه میشوید که در کدنویسی به زبان php، برای نامگذاری از یک طرح ثابت استفاده نمیشود:

()strpos() vs. str_split

()imagetypes() vs. image_type_to_extension

هنگام شروع کد نویسی، برنامه نویس برای نامگذاری ها باید از یک متد یا الگو استاندارد استفاده کند. انواع مختلفی از این الگو ها وجود دارد که دو تا از مشهورترین و استانداردترین آنها دو روش زیر است:

camelCase:

در این روش کلمه اول با حرف کوچک شروع میشود و بقیه کلمه های بعدی از با حرف بزرگ شروع میشوند.

مثل : ()parseRawImageData

underscores:

در این روش تمام کلمات با حرف کوچک شروع میشوند و با استفاده از کاراکتر _ از هم جدا میشوند.

مثل : ()mysql_real_escape_string

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

معمولا بعضی از پلتفرم های زبان برنامه نویسی، مایل هستند که هنگام نامگذاری از یک مدل ثابت استفاده کنند. برای مثال در کدنویسی به زبان java بیشتر از روش camelCase برای نامگذاری استفاده می شوند در حالی که در زبان برنامه نویسی PHP نامگذاری ها از روش underscores انجام میشوند.

توجه داشته باشید که این روش ها میتوانند با هم میکس شوند برای مثال بعضی از برنامه نویسان با توجه به نوع پروژه خود ترجیح میدهند از روش underscores برای نامگذاری توابع و کلاس ها استفاده کنند و از روش camelCase برای نامگذاری متد های کلاس ها استفاده کنند:

class Foo_Bar {
 
    public function someDummyMethod() {
 
    }
 
}
 
function procedural_function_name() {
 
}

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

6. قاعده DRY در کدنویسی

واژه DRY مخفف عبارت (Don’t Repeat Yourself) به معنی” خودت تکرار نکن” است که بعنوان DIE مخفف عبارت (Duplication is Evil) به معنی کپی برداری مضر است، شناخته شده است.

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

برای مثال بیشتر برنامه های تحت وب صفحات زیادی دارند که در آنها عناصر مشترک زیادی مثل هدرها و فوترها وجود دارد. کپی-پیست کردن آنها در تمام صفحات ایده مناسبی نیست.به جای کپی-پیست کردن توصیه میشود که کد های مربوط به هدر و فوتر را در سورس فایل های جداگانه قرار دهید و هر جا که به آنها نیاز داشته داشتید به راحتی بتوانید به انها دسترسی داشته باشید و استفاده کنید.

$this->load->view('includes/header');
 
$this->load->view($main_content);
 
$this->load->view('includes/footer');

7. خودداری از ایجاد تودرتویی های عمیق در کد

استفاده زیاد از سطوح تودرتو کار خواندن و دنبال کردن کدها را سخت تر میکند.

function do_stuff() {
 
// ...
 
    if (is_writable($folder)) {
 
        if ($fp = fopen($file_path,'w')) {
 
            if ($stuff = get_some_stuff()) {
 
                if (fwrite($fp,$stuff)) {
 
                    // ...
 
                } else {
                    return false;
                }
            } else {
                return false;
            }
        } else {
            return false;
        }
    } else {
        return false;
    }
}

برای خوانایی بیشتر، می توان تغییراتی مثل کم کردن سطوح تودرتو در کدها را ایجاد کرد.

function do_stuff() {
 
// ...
 
    if (!is_writable($folder)) {
        return false;
    }
 
    if (!$fp = fopen($file_path,'w')) {
        return false;
    }
 
    if (!$stuff = get_some_stuff()) {
        return false;
    }
 
    if (fwrite($fp,$stuff)) {
        // ...
    } else {
        return false;
    }
}

8. محدودسازی طول خط ها کد در برنامه نویسی

اگر دقت کرده باشید مقالات موجود در مجله و روزنامه های انگلیسی، در قالب ستون های باریک و بلند نوشته شده اند که این نوع چیدمان باعث میشود که ما راحت تر بتوانیم مطالب را ببینیم و بخوانیم:

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

// bad
$my_email->set_from('[email protected]')->add_to('[email protected]')->set_subject('Methods Chained')->set_body('Some long message')->send();
 
// good
$my_email
    ->set_from('[email protected]')
    ->add_to('[email protected]')
    ->set_subject('Methods Chained')
    ->set_body('Some long message')
    ->send();
 
// bad
$query = "SELECT id, username, first_name, last_name, status FROM users LEFT JOIN user_posts USING(users.id, user_posts.user_id) WHERE post_id = '123'";
 
// good
$query = "SELECT id, username, first_name, last_name, status
    FROM users
    LEFT JOIN user_posts USING(users.id, user_posts.user_id)
    WHERE post_id = '123'";

9. سازماندهی فایل و پوشه ها

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

از این رو برای کنترل بهتر، دسترسی آسانتر و راحت تر خواندن کد ها بهتر است که یک پوشه بسازید و با توجه به نیاز و کدهایتان فایل هایی برای نگه داری کدهای مربوطه در آن ایجاد کنید.

10. نام های موقت ثابت

بطور کلی متغیرها باید قابل توصیف و شامل یک یا چند کلمه باشند. اما متغیرهای موقتی نیاز به این ویژگی ها ندارند و می توانند به اندازه یک کاراکتر کوتاه باشند.

یک روش بسیار خوب دیگر استفاده از نام های ثابت برای متغیرهای ثابتی است که یک نوع نقش دارند. به مثال زیر توجه کنید:

// $i for loop counters
for ($i = 0; $i < 100; $i++) {
 
    // $j for the nested loop counters
    for ($j = 0; $j < 100; $j++) { } } // $ret for return variables function foo() { $ret['bar'] = get_bar(); $ret['stuff'] = get_stuff(); return $ret; } // $k and $v in foreach foreach ($some_array as $k => $v) {
 
}
 
// $q, $r and $d for mysql
$q = "SELECT * FROM table";
$r = mysql_query($q);
while ($d = mysql_fetch_assocr($r)) {
 
}
 
// $fp for file pointers
$fp = fopen('file.txt','w');

11. نوشتن کلمات خاص SQL با حروف بزرگ

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

SELECT id, username FROM user;
 
UPDATE user SET last_login = NOW()
WHERE id = '123'
 
SELECT id, username FROM user u
LEFT JOIN user_address ua ON(u.id = ua.user_id)
WHERE ua.state = 'NY'
GROUP BY u.id
ORDER BY u.username
LIMIT 0,20

12. جداسازی کد و داده برای خوانای بیشتر کد

این روش یک اصل و قاعده دیگر برای خوانای کدهاست که میتوان آن را بر روی تمام زبان های برنامه نویسی و همه محیط ها اعمال کرد.

معمولا واژه data یا داده در زمینه توسعه وب، به معنی خروجی HTML است.

سال ها پیش وقتی که php برای اولین بار منتشر شد، در ابتدا به عنوان یک موتور الگو شناخته شده.

داشتن فایل های بزرگ HTML که در بین آن چند خط کد php داشته باشد، یک کار معمولی بود. در حالی که بعد از سالها همه چیز تغییر کرد و وب سایت ها پویاتر و کاربردی تر شدند.اکنون کد، یک بخش عظیم از برنامه های تحت وب است و دیگر این روش خوبی برای ترکیب آن با HTML نیست.

شما میتوانید این اصل و قاعده را در برنامه خود پیاده سازی کنید و یا میتوانید از یک ابزار سه طرفه (third-party) که شامل موتورهای الگو، فریم ورک ها یا CMS ها است که قرارداد های آنها را دنبال میکند.

13. جا به جایی syntax ها در داخل الگوها

ممکن است که شما از یک موتور الگو فانتزی استفاده نکنید و به جای آن با php درون خطی ساده در فایل هایتان ادامه دهید. این لزوما “جداسازی کد و داده” را نقض نمی کند به شرطی که کد درون خطی مستقیما با خروجی ارتباط دارد و قابل خواندن است. در این مورد شما باید از جایگزین کردن syntax برای ساختارهای کنترل استفاده کنید.

<div class="user_controls">

<?php if ($user = Current_User::user()): ?>

Hello, <em><?php echo $user->username; ?></em> <br/>

<?php echo anchor('logout', 'Logout'); ?>

<?php else: ?>

<?php echo anchor('login','Login'); ?> |

<?php echo anchor('signup', 'Register'); ?>

<?php endif; ?>

</div>

<h1>My Message Board</h1>

<?php foreach($categories as $category): ?>

<div class="category">

<h2><?php echo $category->title; ?></h2>

<?php foreach($category->Forums as $forum): ?>

<div class="forum">

<h3>

<?php echo anchor('forums/'.$forum->id, $forum->title) ?>

(<?php echo $forum->Threads->count(); ?> threads)

</h3>

<div class="description">

<?php echo $forum->description; ?>

</div>

<?php endforeach; ?>

</div>

<?php endforeach; ?>

با این کار می توانید استفاده زیاد از پرانتز ها را کم کنید و روش ار مثل ساختار و تورفتگی HTML است.

14. Object-Oriented vs. Procedural

برنامه نویسی شی گرا به شما برای ساختن well-structured کمک میکند. اما این بدین معنا نیست که شما باید به طور کلی برنامه نویسی procedural را کنار بگذارید.در واقع ترکیب این دو مدل برنامه نویسی می تواند مفید باشد.

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

class User {
 
    public $username;
    public $first_name;
    public $last_name;
    public $email;
 
    public function __construct() {
        // ...
    }
 
    public function create() {
        // ...
    }
 
    public function save() {
        // ...
    }
 
    public function delete() {
        // ...
    }
 
}

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

function capitalize($string) {
 
    $ret = strtoupper($string[0]);
    $ret .= strtolower(substr($string,1));
    return $ret;
 
}

15. خواندن کد های متن باز

پروژه های متن باز توسط ورودی های تعداد زیادی از توسعه دهندگان ساخته شده اند.

برای اینکه قابلیت خوانایی در پروژه ها حفظ شود، اعضای تیم میتوانند تا جایی که ممکن است با هم کار کنند.

از این رو ، مرور سورس کد پروژه یک ایده خوب برای مشاهده کارهایی که توسط توسعه دهندگان در پروژه انجام شده میباشد.

16. استفاده از نام های معنی دار برای متغیرها و توابع

اگر شما از نام های معنی دار استفاده کنید قطعا در زمان خود صرفه جویی خواهید کرد.

شاید زمانی که شما فقط 10 یا 12 خط برنامه نویسی میکنید این موضوع خیلی هم مهم به نظر نیاید اما برای کد نویسی های طولانی بسیار گیج کننده خواهد بود. همچنین با گذاشتن اسم کوتاه برای متغیرها و توابع در زمان خود صرفه جویی کرده اید.

17. استفاده نکردن از اعداد جادویی در برای خوانایی کد

منظور از اعداد جادویی در برنامه نویسی، استفاده از مقدار عددی hard-coded در کد است. ممکن است که هنگام کدنویسی استفاده از چنین عدد هایی برای شما امری منطقی باشد. در حالی که ممکن است شما یا هر شخص دیگری بطور همزمان به یک قطعه کد نگاه کنید و به سختی متوجه شوید که در آینده این شماره قرار است چه کاری انجام دهد.

<?php

while($egg_count > 400) {

// Do something

}

$container_capacity = 400;

while($egg_count > $container_capacity) {

// Do Something

}

?>

به کد بالا توجه کنید. در قسمت اول کد ما نمی فهمیم که عدد 400 تعداد چه چیزی را نشان میدهد.آیا منظور آن تعداد افرادی است که تخم مرغ سرو میکنند یا چیز دیگری است؟ از سوی دیگر ما بطور کامل و واضح میدانیم که در این برنامه، در حال بررسی این هستیم که اگر تعداد تخم مرغ بیشتر از ظرفیت کانتینر ها شد چه کاری انجام شود.

18. کدهای قابل بازسازی

عمل بازسازی (refactoring) یعنی اعمال یک سری تغییرات بر روی کدها، بدون اینکه که عملکرد آن برنامه و کد تغییر کند. بازسازی کد ها شامل تغییراتی مثل رفع اشکالات یا اضافه کردن قابلیت های جدید به کد نمیشود از این رو به منظور بهبود خوانایی و کیفیت، می توانید آن را به عنوان یک “cleanup” ببینید.

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