كيفية كتابة أسماء أفضل لمتغيراتك، ودوالك، وفصولك – مع أمثلة

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

سيعمل هذا المقال كدليل شامل حول كيفية وضع أسماء ذات معنى لأسماء الفئات والمتغيرات والوظائف مع أمثلة وأفضل الممارسات.

لماذا تهم التسمية؟

• قراءة سهلة: الأسماء الجيدة تجعل رمزك بديهيًا وتقلل من منحنى التعلم لدى الآخرين.

• سهولة الصيانة: من الأسهل إعادة تنظيم أو تصحيح الرمز المسمى جيدًا.

• التعاون: الأسماء الواضحة تحسن تواصل الفريق وإنتاجيته.

• التوسعية: الأسماء ذات المعنى تساعد في الحفاظ على مشاريع كبيرة قابلة للإدارة.

أساليب تسمية مختلفة

أساليب تسمية مختلفة ضرورية في تحسين قراءة الرمز وصيانته عبر مختلف لغات البرمجة.

أنماط مثل camelCase و PascalCase و snake_case و kebab-case مصممة لتناسب سياقات وممارسات محددة.

camelCase تُستخدم على نطاق واسع للمتغيرات والدوال، في حين أن PascalCase مفضلة للفئات. snake_case مفضلة في بايثون لوضوحها، و kebab-case تهيمن على CSS لتنسيق عناصر HTML.

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

كيفية اختيار النمط الصحيح

1. خاص باللغة: اتبع تقاليد لغة البرمجة أو الإطار الخاص بك. على سبيل المثال:

   • JavaScript: camelCase للمتغيرات والدوال، PascalCase للمكونات.

   • Python: snake_case للمتغيرات والدوال.

   • CSS/HTML: kebab-case لأسماء الفئات والمعرفات.

2. معايير الفريق أو المشروع: الاستمرارية مهمة. استخدم النمط المتفق عليه لفريقك/مشروعك.

3. خاص بالغرض: استخدم أساليب التسمية التي تمثل الكيان المسمى بشكل أفضل (على سبيل المثال، الثوابت بتنسيق SCREAMING_SNAKE_CASE).

إرشادات عامة للتسمية

قبل الانغماس في توجيهات التسمية الخاصة بأسماء الفئات والمتغيرات والوظائف، دعنا نستكشف بعض المبادئ العالمية:

1. كن وصفيًا وموجزًا: يجب أن تنقل الأسماء الغرض أو الدور الخاص بالمتغير/الوظيفة/الخ:

    // سيء
    let x = 10;
   
    // جيد
    let maxUsersAllowed = 10;
   

2. تجنب الاختصارات الصعبة التي قد تكون صعبة على المطورين الآخرين فهمها (أو حتى على نفسك في المستقبل):

    // سيئ
    let usrNm = "John";
   
    // جيد
    let userName = "John";
   

3. استخدم توحيد الأسماء: اختر نمطًا للتسمية (camelCase، PascalCase، kebab-case، snake_case) وتمسك به طوال مشروعك.

4. تجنب الكلمات المحجوزة أو الأسماء المربكة:

    // سيء
    let let = 5;
   
    // جيد
    let variableName = 5;
   

حسنًا، الآن بعد أن غطينا الأساسيات، دعونا ننزل في التفاصيل حول بعض التوجيهات الجيدة لتسمية العناصر.

كيفية إنشاء أسماء فئة جيدة

تحدد أسماء الفئات السلوك البصري أو الهيكلي للعناصر في تطبيقك. كتابة أسماء فئات واضحة تضمن سهولة فهم وصيانة HTML و CSS الخاصة بك.

1. استخدم أسماء وصفية

يجب أن تصف أسماء الفئات الغرض من العنصر، وليس مظهره.

<!-- سيء -->
<div class="red-button"></div>

<!-- جيد -->
<div class="primary-button"></div>

2. اتبع منهجية BEM (Block-Element-Modifier)

BEM هي معايير شائعة لكتابة CSS قابلة للتوسع والصيانة. تقوم بفصل المكونات إلى:

• كتلة: تمثل المكون (على سبيل المثال، card).

• عنصر: يمثل عناصر الأطفال للكتلة (على سبيل المثال، card__title).

• معدل: يمثل تغييرات على الكتلة أو العنصر (على سبيل المثال، card__title--highlighted).

مثال:

<div class="card">
  <h1 class="card__title card__title--highlighted">Welcome</h1>
  <p class="card__description">This is a card component.</p>
</div>

3. استخدم kebab-case

أسماء فئات CSS تُكتب تقليديًا بتنسيق kebab-case لزيادة قراءتها.

<!-- سيئ -->
<div class="primaryButton"></div>

<!-- جيد -->
<div class="primary-button"></div>

كيفية إنشاء أسماء متغيرات جيدة

المتغيرات تحمل البيانات ويجب أن تحمل أسماء ذات معنى تصف ما تمثله.

1. استخدم الأسماء للمتغيرات

المتغيرات تكون عادة اسماء أسماء لأنها تمثل كيانات أو بيانات.

// سيئ
let a = "John";

// جيد
let userName = "John";

2. استخدم البادئات لإضافة سياق

إضافة بادئات تساعد في توضيح نوع أو هدف المتغير:

• بوليان: هو, لديه, يستطيع

• أرقام: أقصى, أدنى, مجموع

• مصفوفات: استخدم الأشكال الجمعية (على سبيل المثال، المستخدمين, العناصر).

مثال:

let isUserLoggedIn = true;
const maxUploadLimit = 5; // ميجابايت
const usersList = ["John", "Jane"];

3. تجنب الأسماء العامة

تجنب الأسماء مثل البيانات, القيمة, أو العنصر ما لم تكن ضرورية.

// سيء
let data = 42;

// جيد
let userAge = 42;

كيفية إنشاء أسماء دوال جيدة

الدوال تقوم بأداء أفعال، لذا يجب أن تعكس أسماؤها العملية أو العملية التي تقوم بها.

1. استخدم أفعال للدوال

الدوال موجهة للعمل، لذا يجب أن تبدأ أسماؤها بفعل:

// سيء
function userData() {
  // ...
}

// جيد
function fetchUserData() {
  // ...
}

2. كن محددًا حول الوظائفية

يجب أن تشير أسماء الدوال إلى ما تفعله.

// سيء
function handle() {
  // ...
}

// جيد
function handleFormSubmit() {
  // ...
}

3. استخدم البادئات للدلالة على النية

• للمعالجات الحدثية: handle, on

• للأدوات: calculate, convert, format

• لعمليات الجلب: fetch, get, load

• للمعلمات والمسترجعات: set, get

مثال:

function handleButtonClick() {
  console.log("Button clicked!");
}

function calculateDiscount(price, discountPercentage) {
  return price * (discountPercentage / 100);
}

كيف تعرف إذا كان اسم ما جيداً لمتغير أو دالة أو فئة

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

1. هل يمثل الغرض؟

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

كيفية التقييم:

اسأل نفسك: “عند قراءتي لهذا الاسم، هل يمكنني فهم الغرض منه على الفور؟”

مثال:

• سن_المستخدم أفضل من أ لأن سن_المستخدم يخبرك بما يمثله المتغير، بينما أ غامض جدًا.

2. هل هو كافٍ من الناحية الخاصة؟

يجب أن يكون الاسم كافيًا من الناحية الخاصة ليعكس الدور الدقيق للكيان في الشيفرة الخاصة بك. الأسماء العامة بشكل مفرط مثل البيانات أو temp يمكن أن تكون مربكة لأنها لا توفر سياقًا كافيًا.

كيفية التقييم:

اسأل: “هل هذا الاسم محدد لما يمثله هذا المتغير أو الدالة أو الصنف في تطبيقي؟”

مثال:

• حساب_مبلغ_الضريبة() أفضل من حساب() لأنه من الواضح ما تقوم به الدالة.

3. هل يتبع توجيه أسماء ثابت؟

الاتساق في توجيه الأسماء أمر حيوي. عندما يتبع جميع أعضاء الفريق نفس التوجيهات، يصبح من الأسهل فهم الشيفرة وتصفحها.

كيفية التقييم:

اسأل: “هل هذا الاسم متسق مع التعليمات المستخدمة في بقية المشروع؟” اتبع إرشادات المشروع مثل:

• camelCase للمتغيرات والدوال (على سبيل المثال، userAge)

• PascalCase للكلاسات (على سبيل المثال، UserProfile)

• UPPERCASE_SNAKE_CASE للثوابت (على سبيل المثال، MAX_USERS)

مثال:

• إذا كان فريقك يتبع camelCase، فإن userData أفضل من UserData.

4. هل يتجنب الغموض؟

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

كيفية التقييم:

اسأل: “هل يمكن لشخص غير ملم بقاعدة الأكواد أن يسيء فهم ما يشير إليه هذا الاسم؟”

مثال:

• بدلاً من تسمية قيمة بوليانية بـ isValid، استخدم isUserLoggedIn أو isEmailVerified لجعل الأمر أوضح حول ما يتم فحصه.

5. هل من السهل قراءته ونطقه؟

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

كيفية التقييم:

اسأل: “هل هذا الاسم سهل القراءة بصوت عالٍ، وهل يمكنني فهمه على الفور؟”

تجنب الأسماء الطويلة، واستخدم الاختصارات الشائعة فقط عندما يتم قبولها على نطاق واسع.

مثال:

• maxRetries أفضل من maximumNumberOfAttemptsToReconnect.

6. هل يتجنب التكرار؟

تجنب التكرار في الأسماء. لا تكرر المعلومات التي يتم تلميحها أو وصفها بالفعل من قبل السياق.

كيفية التقييم:

اسأل: “هل أكرر معلومات واضحة بالفعل من السياق المحيط؟”

مثال:

• إذا كان لديك فئة تحمل اسم User، فإن تسمية طريقة بـ userGetData() مكررة. في حالتها، استخدم getData().

7. هل هو يوثق نفسه؟

أفضل الأسماء توثق ذواتها. تقلل الأسماء الجيدة من الحاجة إلى تعليقات أو شروحات إضافية.

كيفية التقييم:

اسأل: “هل يصف هذا الاسم بشكل كامل المتغير أو الدالة أو الفئة دون الحاجة لتعليق لشرح ما يفعل؟”

مثال:

• calculateTotalPrice مفهوم بذاته، لذا لا حاجة لتعليق إضافي مثل “تقوم هذه الدالة بحساب السعر الإجمالي بعد الخصم.”

8. هل هو سياقي وملائم لنطاق النطاق؟

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

كيفية التقييم:

اسأل: “هل هذا الاسم متناسب مع نطاق وسياق مشروعي؟”

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

مثال:

• في تطبيق ألعاب، healthPoints هو أكثر ملائمة من hp، حيث يعكس معناه بشكل أفضل.

9. هل هو مقاوم للتطور؟

فكر في كيفية تطور كودك. يجب أن تكون الأسماء مرنة بما يكفي لاستيعاب التغييرات المستقبلية دون الحاجة إلى إعادة تسمية.

كيفية التقييم:

اسأل: “هل سيظل هذا الاسم مناسبًا إذا تغيرت الوظائف أو نما المشروع؟”

مثال:

• userInfo يمكن أن يصبح قديمًا إذا تغيرت هيكلة البيانات. من الأفضل استخدام userProfile إذا كنت تتوقع إضافة حقول إضافية.

10. هل يتجنب الأرقام السحرية والقيم المشفرة صعبة الكود؟

أرقام سحرية (أرقام غير واضحة المعنى) يجب تجنبها لصالح الثوابت المسماة.

كيفية التقييم:

اسأل: “هل هذا الاسم يمثل ثابتًا ذو معنى، أم أنه مجرد رقم خام؟”

مثال:

• بدلاً من استخدام 1000، استخدم ثابتًا مثل MAX_FILE_SIZE لشرح المعنى وراء الرقم.

أمثلة عملية

مثال CSS

يوضح المثال التالي لـ CSS كيفية تطبيق توجيهات تسمية BEM (Block-Element-Modifier) للحفاظ على تسلسل هرم الفئات المنظم والقابل للتوسع في ورقة الأنماط الخاصة بك:

<!-- HTML -->
<div class="navbar">
  <ul class="navbar__list">
    <li class="navbar__item navbar__item--active">Home</li>
    <li class="navbar__item">About</li>
    <li class="navbar__item">Contact</li>
  </ul>
</div>

/* CSS */
.navbar {
  background-color: #333;
  padding: 10px;
}

.navbar__list {
  list-style: none;
}

.navbar__item {
  display: inline-block;
  padding: 10px;
}

.navbar__item--active {
  color: orange;
}

هنا ما يحدث في هذا الكود:

• تسمية BEM: navbar هو الـ Block، يمثل مكون التنقل الرئيسي.

• navbar__list هو الـ Element، هو ابن الـ Block، يمثل قائمة عناصر التنقل.

• navbar__item هو عنصر آخر Element يمثل عناصر القائمة الفردية.

• navbar__item--active هو تعديل، يستخدم لتحديد عنصر القائمة النشط.
  تجعل هذه الطريقة من السهل فهم العلاقات والأدوار داخل HTML و CSS، وتدعم الأنماط القابلة للتوسيع والإعادة الاستخدام.

مثال على JavaScript

يوضح هذا المثال على JavaScript كيفية استخدام تسميات معنوية ومتسقة للمتغيرات والدوال لجعل الكود مفهومًا ذاتيًا:

// المتغيرات
let isUserLoggedIn = false;
const maxAllowedItems = 10;

// الدوال
function fetchUserDetails(userId) {
  // جلب بيانات المستخدم من الواجهة البرمجية للتطبيقات
}

function calculateTotalPrice(cartItems) {
  return cartItems.reduce((total, item) => total + item.price, 0);
}

هنا ما يحدث في الكود:

• المتغيرات:

  • isUserLoggedIn: متغير منطقي مسمى بوضوح لدلالته. تسبيقه بـis يساعد في تحديد أنه متغير منطقي.

  • maxAllowedItems: ثابت بتسمية علوية بـmax يوضح أنه حد، مما يجعل نية استخدامه واضحة.

• الدوال:

  • fetchUserDetails(userId): الاسم يعكس غرض الدالة، وهو استرداد تفاصيل المستخدم. المعامل userId وصفي ويتجنب الغموض.

  • calculateTotalPrice(cartItems): اسم الدالة يحدد بوضوح الإجراء المنفذ. المعامل cartItems ذو صلة سياقية بمجال التجارة الإلكترونية.

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

الاستنتاج

التسميات المعنوية هي تقليد مهم وفن يؤثر بشكل كبير على قابلية قراءة وصيانة الكود الخاص بك.

حاول اتباع هذه المبادئ الأساسية:

• استخدم أسماء وصفية وموجزة.

• تمسك بتقاليد ثابتة مثل BEM لأسماء الفئات و camelCase للمتغيرات والدوال.

• استخدم بادئات لإضافة سياق ووضوح.

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