على مدى السنوات الخمس الماضية، كنت أحاول باستمرار تحسين مهاراتي في البرمجة، وكان أحدها هو تعلم واتباع أنماط البرمجة الموصى بها.
يهدف هذا الدليل إلى مساعدتك في كتابة تعليمات برمجية متسقة وأنيقة ويتضمن بعض النصائح لتحسين إمكانية قراءة التعليمات البرمجية وإمكانية صيانتها. إنه مستوحى من الإرشادات الشائعة الأكثر قبولًا داخل المجتمع ولكن لديه بعض التعديلات ليتناسب بشكل أكثر ملاءمة مع تفضيلاتي.
ومن الجدير بالذكر أنني مطور جافا سكريبت متكامل، وجميع ملاحظاتي خاصة بمكدس التكنولوجيا الخاص بي (MEVN) وقد لا تنطبق على مكدسات أخرى.

القواعد العامة

تجنب تكرار التعليمات البرمجية

إذا كانت هناك حاجة لكتابة نفس مقطع التعليمات البرمجية (أو مع بعض الاختلافات التي يمكن التحكم فيها) في أكثر من مكان واحد، فمن من الضروري دمجها في وظيفة، وبعد ذلك، استدعاء الوظيفة كلما ضروري.

النظر في اقتران فضفاض

يجب أن تعمل الوظائف بشكل مستقل، مما يعني أن تحرير إحداها يجب أن لا يكون له أي تأثير على الإطلاق على الوظائف الأخرى طالما ظلت المدخلات والمخرجات كما هي. يجب أن لا يكون لكل وظيفة أي معرفة بتعريفات الوظائف الأخرى وأن تعمل كمكون منفصل. في هذه الحالة، كل ما تعرفه هو معلماتها، وبغض النظر عمن يستدعي الوظيفة، فإن نفس المدخلات دائمًا ما تُرجع نفس النتائج.

تصريح

أولاً وقبل كل شيء، تذكر أن تعلن عن المتغيرات طوال الوقت.

استخدم الكلمة الأساسية const عندما لا يتم إعادة تعيين المتغير. ومع ذلك، لا يزال بإمكانك استخدام const للمتغيرات التي هي كائنات أو صفائف، حتى إذا كنت تخطط لإعادة تعيين عناصرها المتداخلة.
يرجى ملاحظة أنك تحتاج إلى وحدات وتحديد المتغيرات الثابتة دائمًا باستخدام الكلمة الأساسية const.
استخدم الكلمة الأساسية Let عندما لا تتمكن من استخدام const، واستخدم الكلمة الأساسية var فقط إذا كنت بحاجة إلى دعم المتصفحات الأقدم.

وظائف

يجب أن تقتصر الوظائف على ما يلي:

أربعة متغيرات
أربع معلمات
ثلاثون سطرًا من التعليمات البرمجية (تجاهل التعليقات)
أربعة فروع (إذا كان الأمر كذلك، أثناء، أو، أو، حالة التبديل)

يجب أن تقتصر سطور الكود على 100 حرف، ومن أجل تجميع/تنظيم الوظائف، فمن الأفضل إبقاء الوظائف ذات الصلة قريبة من بعضها البعض قدر الإمكان.

منح امتياز بناء جملة دالة السهم للبديل التقليدي كلما كان ذلك ممكنًا.

سلاسل

استخدم علامات الاقتباس المفردة ' (بدلاً من علامات الاقتباس المزدوجة ") للسلاسل الحرفية العادية، ولكن بالنسبة للسلاسل التي تحتوي على متغيرات/تعبيرات مضمنة، وسلاسل أسطر متعددة، والسلاسل التي تحتوي على أحرف اقتباس مفردة، استخدم قوالب حرفية.

تسمية

من الضروري الحفاظ على الاتساق عند تسمية المتغيرات. وهذا يعني أنه إذا كانت المتغيرات الموجودة في صفحات مختلفة مسؤولة عن نفس البيانات، فيجب أن يكون لها نفس الاسم.

يجب أن تكون أسماء المتغيرات والوظائف والأساليب والمعلمات ذاتية الوصف، مما يعني أنه يجب أن يكون أي شخص قادرًا على معرفة (أو على الأقل التخمين العادل) حول البيانات المضمنة بمجرد النظر إلى أسمائهم.

يجب أن تكون المتغيرات الثابتة بأحرف كبيرة، مع فصل الكلمات بشرطات سفلية. يجب أن تتبع الوظائف والمتغيرات والأساليب بناء جملة CamelCase، بينما يجب أن تتبع فئات ومعرفات CSS بناء جملة حالة الكباب.

تعليقات

يجب أن تبدأ التعليقات دائمًا بحرف كبير وتقتصر على 100 حرف. قد تتذكر أن أسطر التعليمات البرمجية ستتبع نفس القاعدة، ولكن لاحظ أنه إذا كانت الأسطر تتضمن كليهما، فيمكن أن تتجاوز ما يصل إلى 150 حرفًا فقط.

لا ينبغي كتابة التعليقات التي تصف الوظائف حيث يتم استدعاؤها ولكن حيث يتم تعريفها.

ضع التعليقات بعد رموز السطر الواحد ما لم يتجاوز طول السطر 150 حرفًا. في مثل هذه الحالات، وبالنسبة للأكواد المتعددة الأسطر، ضع التعليقات في الأعلى.

بخصوص عبارات if، يجب وضع التعليقات بعد العبارات الشرطية.

if (conditionIsTrue) { // ضع تعليقك هنا doSomeThing(); } else { // ضع تعليقك هنا doSomethingElse(); }

if (conditionIsTrue) { // Put your comment here
    doSomeThing();
} else { // Put your comment here
    doSomethingElse();
}

تذكر استخدام الشرطة المائلة المزدوجة // للتعليقات المكونة من سطر واحد و/* */ للتعليقات متعددة الأسطر. عند إضافة تعليقات متعددة الأسطر إلى رمز من سطر واحد أو عبارات شرطية، ضعها داخل /* */ بحيث يتم كتابة /* أمام الكود، ويبدأ التعليق في السطر التالي، ويتم كتابة */ في سطر جديد خط.

إذا (الحالة صحيحة) { /* ضع تعليقك هنا ضع تعليقك هنا */ doSomeThing(); } اسم الوظيفة (المعلمة)، /* ضع تعليقك هنا ضع تعليقك هنا */

if (conditionIsTrue) { // Put your comment here
    doSomeThing();
} else { // Put your comment here
    doSomethingElse();
}

وظيفة التعليقات الوصفية

ضع التعليقات أعلى الوظائف المغلفة بـ /** */.

وصف المعلمات باستخدام @param {type} وصف اسم المتغير.
إذا كانت المعلمة يمكنها قبول أكثر من نوع متغير واحد، فاستخدم @param {type1 | type2} وصف اسم المتغير.
إذا كانت المعلمة اختيارية ومن الممكن أن تكون غائبة، فاستخدم وصف @param {type} [variableName].
إذا كانت المعلمة لها قيمة افتراضية (يجب أن تكون اختيارية حتى يكون لها قيمة افتراضية بالفعل)، فاستخدم وصف @param {type} [variableName="value"].
قم بوصف مخرجات الوظيفة باستخدام وصف @returns {type}.

/** * وصف الوظيفة هنا * @param {type} NormalVariable متغير عادي * @param {type1 | type2} multiTypeVariable متغير ذو أنواع متعددة متوقعة * @param {type} [variableWithDefaultValue="value"] متغير اختياري له قيمة افتراضية في حالة غيابه عند استدعاء الدالة * @param {type} [اختياري متغير] متغير اختياري *وصف @returns {type}. */ const functionName = (normalVariable, multiTypeVariable,variableWithDefaultValue, OptionalVariable) => { doSomeThing(); }

if (conditionIsTrue) { // Put your comment here
    doSomeThing();
} else { // Put your comment here
    doSomethingElse();
}

فيما يتعلق بوظائف الخادم ذات معلمات req وres، ليست هناك حاجة لوصف معلمات الطلب؛ قم بوصف الاستجابة فقط باستخدام وصفreturns.

/** * وصف الوظيفة هنا * @إرجاع الوصف */ اسم الوظيفة = (req, res) => { doSomeThing(); }

if (conditionIsTrue) { // Put your comment here
    doSomeThing();
} else { // Put your comment here
    doSomethingElse();
}

بشكل عام، ليست هناك حاجة لوصف المعلمات req و res و next و to و from.

في ملفات HTML، استخدم لفصل الأجزاء المختلفة من الكود؛ وبالتالي يمكن للمستخدم التعرف على كل جزء بسهولة.

في حالة كتابة تعليقات في منتصف سطر من التعليمات البرمجية، استخدم /* */.

const calc_result = (firstNumber * SecondNumber)/* شرح سبب الضرب */ ThirdNumber;

if (conditionIsTrue) { // Put your comment here
    doSomeThing();
} else { // Put your comment here
    doSomethingElse();
}

المسافة البادئة

ممنوع إضافة مسافة بيضاء.

تذكر دائمًا وضع مسافات حول التعبيرات وعوامل التشغيل والرموز، وأيضًا بعد الفواصل والأقواس المتعرجة، إذا كانت
ليست الأحرف الأخيرة في السطر. يُسمح بالأسطر الفارغة (والمطلوبة) فقط في نهاية الملف (يجب أن تنتهي جميع الملفات بسطر فارغ)، بعد آخر وحدة مستوردة، مع فصل علامات القالب والبرنامج النصي والنمط، وبين مجموعات قواعد CSS.
تذكر استخدام Tab للمسافة البادئة والمسافة للمحاذاة.

طلب

ترتيب متغيرات مخططات النمس وحالة تفاعل Vue للمكونات بالترتيب الأبجدي، ولكن لبقية الوقت قم بترتيب الأسطر من الأقصر إلى الأطول.
قم بترتيب طرق التوجيه حسب ترتيب الوضع، والحصول، والنشر، والحذف، بينما تكون كل واحدة منها بترتيب أبجدي، ويجب تجميع جميع المسارات بناءً على عناوين URL الخاصة بها.

الختام

على الرغم من أن هذه ليست أفضل النصائح على الإطلاق، إلا أنني أعتقد أنها توفر نقطة انطلاق قوية لأي شخص مهتم بتعلم مبادئ التعليمات البرمجية النظيفة.

علاوة على ذلك، على الرغم من أن الالتزام الصارم بهذه القواعد قد يبدو صعبًا في البداية، إلا أنه يصبح أكثر وضوحًا مع الممارسة.

من الضروري التأكيد على ضرورة الالتزام بإرشادات المشروع الحالي عند العمل على قاعدة تعليمات برمجية طويلة المدى، حتى لو لم تكن كافية. إذا كنت جادًا بشأن إعادة النظر في إرشادات المشروع، فكر في التعديلات الأكثر فائدة ودعها يتم إدخالها في المشروع تدريجيًا.

حقوق صورة الغلاف: تصوير لويس جوميز من Pexels