إزاي تكتب كود نظيف وأفضل الممارسات

ملخص

الكود النظيف هو كود قابل للقراءة والصيانة بأسماء ذات معنى، ووظائف صغيرة، ومعالجة سليمة للأخطاء، واختبارات شاملة. استخدم أدوات الفحص الحديثة (ESLint، Ruff، Biome)، والتنسيق الآلي (Prettier)، وممارسات مراجعة الكود لفرض النظافة عبر فريقك ومشاريعك.

"أي أحمق يمكنه كتابة كود يفهمه الكمبيوتر. المبرمجون الجيدون يكتبون كوداً يفهمه البشر." — لا يزال كتاب Clean Code لروبرت سي مارتن مؤثراً، لكن تطوير البرمجيات في عام 2026 يضيف أبعاداً جديدة: كود مكتوب لمساعدة الذكاء الاصطناعي، مفروض بواسطة أدوات فحص حديثة، ومنسق تلقائياً، ومُراجع بشكل تعاوني.

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

مبادئ الكود النظيف (ما وراء البديهيات)

أسماء ذات معنى

الأسماء السيئة تجبر القراء على فك تشفير غرض الكود:

// Bad: What does "d" mean? How many days?
const d = new Date();
const diff = today - d;

// Good: Names explain purpose
const accountCreationDate = new Date();
const daysSinceAccountCreation = today - accountCreationDate;

يجب أن تجيب الأسماء على:

• ماذا يمثل هذا المتغير/الوظيفة؟
• لماذا هو موجود؟
• كيف يجب استخدامه؟

اسم المتغير الجيد يوفر ساعات من تصحيح الأخطاء في المستقبل.

وظائف صغيرة بمسؤولية واحدة

الوظائف التي تقوم بشيء واحد بشكل جيد يسهل اختبارها وإعادة استخدامها وفهم منطقها:

// Bad: Does multiple things (fetch, parse, transform, cache)
async function getUserData(userId) {
  const response = await fetch(`/API/users/${userId`);
  const json = await response.json();
  const transformed = {
    id: json.id,
    fullName: `${json.first ${json.last`,
    email: json.email_address,
  };
  cache.set(userId, transformed);
  return transformed;
}

// Better: Separated concerns
async function fetchUser(userId) {
  const response = await fetch(`/API/users/${userId`);
  return response.json();
}

function transformUserData(rawUser) {
  return {
    id: rawUser.id,
    fullName: `${rawUser.first ${rawUser.last`,
    email: rawUser.email_address,
  };
}

async function getUserDataCached(userId) {
  if (cache.has(userId)) return cache.get(userId);
  const rawUser = await fetchUser(userId);
  const user = transformUserData(rawUser);
  cache.set(userId, user);
  return user;
}

القاعدة: إذا كان وصف وظيفتك يتضمن كلمة "و"، فمن المحتمل أنها تنتهك مبدأ المسؤولية الواحدة.

معالجة الأخطاء جزء من الكود النظيف

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

// Bad: Silent failure
function parseConfig(json) {
  try {
    return JSON.parse(json);
  } catch (e) {
    return null;  // What went wrong? Silent failure = nightmare
  }
}

// Better: Clear error messages and types
function parseConfig(json) {
  try {
    if (!json || typeof json !== 'string') {
      throw new Error('Config must be a non-empty string');
    }
    return JSON.parse(json);
  } catch (e) {
    if (e instanceof SyntaxError) {
      throw new Error(`Invalid JSON in config: ${e.message`);
    }
    throw e;  // Re-throw unexpected errors
  }
}

معالجة الأخطاء الجيدة:

• توفر سياقاً حول ما فشل ولماذا
• تميز بين الأخطاء القابلة للاسترداد والأخطاء القاتلة
• تسجل الأخطاء في بيئة الإنتاج للمراقبة

التعليقات لا يجب أن تشرح الكود السيئ

// Bad: Comment explains unclear logic
// Get the last character and check if it's a period
const hasPeriod = text[text.length - 1] === '.';

// Good: Clear code + comment explains "why," not "what"
const hasPeriod = endsWithPeriod(text);  // Sentences end with periods for grammar

function endsWithPeriod(text) {
  return text[text.length - 1] === '.';
}

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

نقد حديث: عندما يذهب الكود النظيف بعيداً جداً

مبادئ Clean Code تحظى باحترام واسع، لكن ظهرت بعض الانتقادات:

الإفراط في التجريد: الوظائف الصغيرة ذات الغرض الواحد جيدة، لكن استخراج كل شرط في وظيفة منفصلة يخلق تشتتاً دون وضوح.

// Over-abstracted: Too many tiny functions make the main logic hard to follow
function isValidEmail(email) {
  return hasAtSymbol(email) && hasValidDomain(email) && isNotTooLong(email);
}
const hasAtSymbol = (e) => e.includes('@');
const hasValidDomain = (e) => e.split('@')[1]?.includes('.');
const isNotTooLong = (e) => e.length <= 254;

// Pragmatic: Keep related logic together
function isValidEmail(email) {
  // RFC 5321 — max length is 254 chars
  if (email.length > 254) return false;
  // Must contain @ and domain with dot
  const [local, domain] = email.split('@');
  return local && domain && domain.includes('.');
}

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

الرؤية الحديثة: مبادئ الكود النظيف هي إرشادات وليست قواعد مطلقة. قم بتكييفها مع سياقك.

قابلية قراءة الكود لأدوات الذكاء الاصطناعي

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

خصائص الكود القابل للقراءة بواسطة الذكاء الاصطناعي:

• الغرض الصريح: يمكن للذكاء الاصطناعي استنتاج الغرض من التسمية والهيكل الواضحين
• تلميحات الأنواع: تلميحات أنواع Python وأنواع TypeScript تساعد الذكاء الاصطناعي على فهم المدخلات/المخرجات المتوقعة
• واجهات برمجة تطبيقات موثقة: Docstrings وتعليقات للوظائف العامة
• أنماط متسقة: هيكل الكود المنتظم يساعد في التعرف على الأنماط

مثال باستخدام TypeScript (صديق للذكاء الاصطناعي):

/** Calculates subscription discount based on term length */
function calculateDiscount(termMonths: number): number {
  if (termMonths < 3) return 0;
  if (termMonths < 12) return 0.1;  // 10% for 3-12 months
  return 0.2;  // 20% for 12+ months
}

/** Applies annual discount to subscription tier */
interface PricingTier {
  name: string;
  basePriceMonthly: number;
}

function applyDiscount(tier: PricingTier, termMonths: number): number {
  const discount = calculateDiscount(termMonths);
  return tier.basePriceMonthly * 12 * (1 - discount);
}

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

أدوات الفحص والتنسيق

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

JavaScript/TypeScript: ESLint

جعل ESLint 9.0.0 (الصادر في 5 أبريل 2024) التكوين المسطح (eslint.config.js) هو الافتراضي وأوقف دعم تنسيق .eslintrc القديم. أكمل ESLint 10.0.0 (الصادر في فبراير 2026) الانتقال بإزالة دعم .eslintrc تماماً — يجب على المشاريع التي لا تزال على التنسيق القديم الهجرة إلى التكوين المسطح للترقية. اعتباراً من مايو 2026، يعد ESLint 10 هو الإصدار الرئيسي الحالي.

يبدو التكوين المسطح النموذجي كما يلي:

// eslint.config.js
import js from '@eslint/js';
import eslintPluginReact from 'eslint-plugin-React';

export default [
  js.configs.recommended,
  {
    files: ['**/*.{js,jsx}'],
    languageOptions: {
      ecmaVersion: 2024,
      sourceType: 'module',
    },
    plugins: {
      React: eslintPluginReact,
    },
    rules: {
      'no-unused-vars': 'error',
      'no-console': 'warn',
      'prefer-const': 'error',
    },
  },
];

قواعد ESLint الأساسية للكود النظيف:

• no-unused-vars: اكتشاف الكود غير المستخدم
• no-implicit-any (مع TypeScript): فرض سلامة الأنواع
• prefer-const: تفضيل عدم التغيير (immutability)
• complexity: يجب ألا تكون الوظائف معقدة للغاية
• max-depth: تجنب المنطق المتداخل بعمق

التنسيق: Prettier

يزيل Prettier الجدال حول النمط من خلال تنسيق الكود تلقائياً:

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2
}

سير عمل Prettier + ESLint:

1. يكتشف ESLint الأخطاء المنطقية والأنماط السيئة
2. يقوم Prettier بإصلاح التنسيق تلقائياً
3. تركز مراجعة الكود على الهندسة والمنطق، وليس النمط

Python: Ruff و Pylint

Ruff هو أداة فحص Python حديثة وسريعة:

ruff check .          # Find issues
ruff format .         # Auto-format

التكوين في pyproject.toml:

[tool.ruff]
line-length = 100
target-version = "py310"

[tool.ruff.lint]
select = ["E", "F", "I", "W"]  # Errors, pyflakes, isort, warnings
ignore = ["E501"]  # Ignore line-too-long (formatter handles it)

سلسلة أدوات موحدة: Biome

يوحد Biome (الإصدار الأولي في أغسطس 2023؛ الإصدار المستقر v2.0 "Biotype" في 2025) الفحص والتنسيق لـ JavaScript و TypeScript في ملف ثنائي واحد يعتمد على Rust. أضاف Biome v2 قواعد فحص مدركة للأنواع لا تعتمد على مترجم TypeScript، بالإضافة إلى تحليل ملفات متعددة ودعم المكونات الإضافية عبر GritQL:

{
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "formatter": {
    "enabled": true,
    "indentWidth": 2
  }
}

يعد Biome أسرع بكثير من استخدام ESLint + Prettier بشكل منفصل.

مراجعة الكود كأداة لفرض الكود النظيف

مراجعة الكود تكتشف المشكلات التي تفوتها الأدوات الآلية وتنشر المعرفة:

ممارسات مراجعة الكود الفعالة:

1. التركيز على المنطق والتصميم، وليس النمط: يجب أن تفرض الأدوات النمط؛ بينما يقيم المراجعون الصحة.

2. طرح الأسئلة بدلاً من المطالبة بالتغييرات:

   • سيء: "هذه الوظيفة طويلة جداً، قم بتقسيمها"
   • جيد: "كيف سيكون شكل هذا إذا فصلنا جلب البيانات عن التنسيق؟"

3. اكتشاف الأنماط مبكراً: راجع الكود أثناء كتابته، وليس في طلبات سحب (PRs) ضخمة.

4. الموافقة بسرعة على طلبات السحب الصغيرة: لا تكن أنت العائق. التغييرات الصغيرة والمركزة تتم مراجعتها ودمجها بشكل أسرع.

5. توثيق عملية صنع القرار: لماذا تم اختيار هذا التصميم؟ قم بتضمين روابط لوثائق الهندسة أو سجلات القرارات.

الاختبار ككود نظيف

الكود بدون اختبارات هو كود غير واضح بطبيعته فيما يتعلق بسلوكه المقصود:

// Without tests, what should this function do exactly?
function mergeUsers(user1, user2) {
  return { ...user1, ...user2 };
}

// With tests, behavior is documented
describe('mergeUsers', () => {
  it('combines two users, with user2 properties taking precedence', () => {
    const user1 = { id: 1, name: 'Alice', email: 'alice@example.com' };
    const user2 = { name: 'Alice Updated', email: 'newemail@example.com' };
    expect(mergeUsers(user1, user2)).toEqual({
      id: 1,
      name: 'Alice Updated',
      email: 'newemail@example.com',
    });
  });

  it('preserves properties from user1 that user2 does not override', () => {
    const user1 = { id: 1, name: 'Alice', email: 'alice@example.com', verified: true };
    const user2 = { name: 'Alice Updated' };
    expect(mergeUsers(user1, user2)).toEqual({
      id: 1,
      name: 'Alice Updated',
      email: 'alice@example.com',
      verified: true,
    });
  });
});

يجبرك التطوير المدفوع بالاختبارات (TDD) على التفكير في السلوك المتوقع قبل كتابة التنفيذ، مما يؤدي بشكل طبيعي إلى كود أنظف.

خطوات عملية لتحسين جودة الكود اليوم

1. أضف ESLint/Ruff إلى مشروعك (حتى المشاريع الحالية ستستفيد)
2. قم بتكوين Prettier ودمجه مع محررك للتنسيق عند الحفظ
3. قم بتمكين pre-commit hooks (husky + lint-staged) لاكتشاف المشكلات قبل الإرسال
4. ضع معايير لمراجعة الكود في فريقك (استخدم قوالب PR)
5. اكتب اختبارات للكود الجديد — ابدأ بالمسار السعيد، ثم الحالات الاستثنائية

قم بإعادة الهيكلة تدريجياً — اختر وظيفة واحدة يومياً لتحسينها

اقرأ وناقش الكود بنشاط — مراجعة الكود هي فرصة للتعلم

الخلاصة

الكود النظيف لا يتعلق بالكمال — بل يتعلق بالاستدامة. الكود يُقرأ أكثر بكثير مما يُكتب. الاستثمار في قابلية القراءة يؤتي ثماره من خلال تصحيح أخطاء أسرع، وتطوير ميزات أسهل، وتقليل عبء الصيانة.

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