المبادئ التوجيهية في كتابة الاكواد

قبل ان تقرا الموضوع يجب ان تعلم بعض من اساسيات البرمجة ..

المسافات في كتابة الاكواد
Tabs vs Spaces

من اجل استخدام الملف بالتنسيق الصح و لسهولة الرجوع اليه للقراءة مستقبلا فاننا في phpBB نقوم باضافة المسافات tabs لنضيف المسافات والدقة و الوضوح في التنسيق في الاكواد و يعتبر الtab عبارة عن 4 مسافات Spaces .. فان معظم المحررات تستخدم نفس الطريقة بنفس التنسيق في استخدام الtabs ..
مسافات الtabs قبل السطر البرمجي لا مشكلة منه و لكن داخل السطر سيسبب مشاكل في حال عدم استخدامه بشكل صحيح و يصعب على المستخدم قراءة الكود بالشكل الصحيح
و اليكم مثال على ذلك ..

كود PHP:

{TAB}$mode{TAB}{TAB}= request_var('mode', '');
{TAB}$search_id{TAB}= request_var('search_id', '');

بحيث نستبدل {TAB} بالضغط على المسافة tab في الكيبورد
و سنحصل على التنسيق في السطرين بالاعلى ^^

الترميز
Encoding
نظرا لدعم الترميز في الانظمة حول العالم و اعتماد utf-8 عالميا .. يتوجب علينا حفظ الملفات بترميز utf-8 وبما ان بعض المحررات لا تستعمل utf-8 بشكل افتراضي للترميز .. يفضل التأكد قبل حفظ الملف انه تم حفظه بالترميز الصح ..

رؤوس الملفات
File Headers

هنا عبارة عن الهيدر المستخدم في ملفات php فعند اضافة اي ملف اضيف التالي ..

كود PHP:

/**
*
* @author Original Author ( تم حذف البريد ل...نتدى )
* @author Another Author ( تم حذف البريد ل...نتدى )
*
* @package {PACKAGENAME}
* @version $Id:$
* @copyright (c) 2007 Your Group Name
* @license [url=http://opensource.org/licenses/gpl-license.php]http://opensource.org/licenses/gpl-license.php[/url] GNU Public License
*
*/

و في نظام القوالب

كود PHP:

تسمية المتغيرات / الدوال ..
Variable/Function Naming

يفضل كتابة الاسماء بطريقة مفهومة و عدم استخدام متغيرات غير مفهومة
مثلا اضافة حرف g إلى global كبداية المتغير .. و عدم استخدام اسماء طويلة ..

الاستخدامات الخاطئة في كتابة المتغيرات
مثال

كود PHP:

$currentuser
$variablename
$extendedvariablename

$Current_User
$Variable_Name
$Extended_Variable_Name

$CurrentUser
$VariableName
$ExtendedVariableName

فان بعض المتغيرات تكون بدون اي مسافات .. و بعضهم اكثر من كلمة طويلة و البعض يستخدم احرف كبيرة .. في البرمجة كل شئ ولكن يفضل عدم استخدامهم و ذلك لعدم التشكيك او الخطا في القراءة مستقبلا ..

الصح

كود PHP:

$current_user
$variable_name
$extended_variable_name

وكذلك إلى

كود PHP:

$current_date_and_time
$private_messages_text_un read

باعتباره خطأ
ولكن يستخدم

كود PHP:

$now
$privmsgs_text_unread

بمتغيرات مختصرة و مفهومة ..

التكرار والدوران
Loop Indices
في التكرار يستخدم متغيرات من نوع حرف واحد
و عالميا يستخدم و يفضل استخدام i و j و k الخ الخ الخ
فان كل مرة نغير الحرف داخل عملية التكرار ..

مثال

كود PHP:

for ($i = 0; $i < $outer_size; $i++)
{
for ($j = 0; $j < $inner_size; $j++)
{
for ($k = 0; $k < 3; $k++)
{
foo($i, $j, $k);
}
}
}

كتابة الدوال
يتوجب عدم كتابة سطر لشرح الدالة و كذلك عدم كتابة شئ مختصر .. و انما شئ مفيد
الخطأ

كود PHP:

a_function_which_gets_use r_data_from_a_file()
stristr()

والطريقة الصح

كود PHP:

get_user_data()
print_login_status()
validate_form_data()

الاقواس ..
في phpBB يتم اضافة الاقواس بعد كل الدوال المستخدمه و ذلك للتنسيق ..

الطريقة الخاطئة

كود PHP:

if (condition) do_stuff();

if (condition)
do_stuff();

while (condition)
do_stuff();

for ($i = 0; $i < size; $i++)
do_stuff($i);

الطريقة الصحيحة

كود PHP:

if (condition)
{
do_stuff();
}

while (condition)
{
do_stuff();
}

for ($i = 0; $i < size; $i++)
{
do_stuff();
}

لاحظ كيفية اضافة الاقواس بين الاوامر .. فانه يعطي طابع و سهولة في القراءة ..

كيفية اضافة الاقواس ..
يتم اضافة الاقواس في سطر جديد
و لا يتم اضافة الاقواس في نفس السطر البرمجي
مثال
الكود الخاطئ ..

كود PHP:

if (condition) {
while (condition2) {
for ($i = 0; $i < $size; $i++) {
...}}
} else {
... }

if (condition) {
while (condition2) {
for ($i = 0; $i < $size; $i++) {
...
}
}
} else {
...
}

الكود الصحيح

كود PHP:

if (condition)
{
while (condition2)
{
for ($i = 0; $i < $size; $i++)
{
...
}
}
}
else
{
...
}

while (condition)
{
...
}

function do_stuff()
{
...
}

» فن كتابة الخاطرة
» ( كيفية كتابة الخاطرة