Software Engineer Encyclopedia
0%
Domain 06 · Software Architecture & Design Patterns · Topic 6.10

Clean Code & Refactoring: تحسين الكود خطوة بخطوة من غير تغيير السلوك

Clean Code and Refactoring — Practical Guide

النظافة البرمجية والتسمية والدوال الصغيرة وcode smells وExtract Method وParameter Objects وpolymorphism وcharacterization tests وtechnical debt وstatic analysis.

  • Advanced
  • ~18 min read
  • 18 sections
  • 8 code examples
  • 1 diagrams
  • 5 questions
  • Priority L2 · Important
  • C# 14 · .NET 10

المتطلبات قبل ما تبدأ

خبرة عملية ببناء API بقاعدة بيانات — الأنماط دي حلول لمشاكل لازم تكون شفتها.

مستوى التعمق المطلوب

PRACTICALRefactor a messy class in small, test-protected steps and explain each step.

01

Clean Code مش شكل الكود؛ هو تكلفة تغييره وفهمه

Optimize for the next reader and next change
Deep dive

Clean Code هو كود يوضح intent، يقلل surprises، ويجعل التغيير والاختبار أسهل. مش معناه أقصر code أو أقل عدد أسطر. أحيانًا method أطول قليلًا بأسماء واضحة أفضل من LINQ one-liner معقد. معيارك: هل developer جديد يقدر يفهم behavior والـ invariants والـ failure modes بسرعة؟

Refactoring هو تغيير internal structure من غير تغيير externally observable behavior. لو غيرت behavior و structure في نفس الوقت، صعب تعرف هل bug من refactor أم feature. لذلك ابدأ tests تحمي behavior، ثم نفذ تغييرات صغيرة، وشغل tests باستمرار.

02

الـ refactoring loop

Safe refactoring cycle
Basics
Characterizetests pin behaviourSmall stepextract / rename / moveTests greenCommitrepeat; red tests → revert the last step, don't debug a big diff
Never refactor without a safety net; small steps, green tests, frequent commits
03

Naming: سمِّ النية وليس نوع المتغير

Names carry domain knowledge
Deep dive

اسم جيد يوضح role/business meaning. elapsedMinutes أفضل من x، و CanBeCancelled أفضل من CheckStatus لو method ترجع boolean. لا تكرر النوع في الاسم مثل productList إذا products كافية. تجنب abbreviations غير المعروفة و generic names مثل Manager/Helper/Processor إلا لو scope واضح.

استخدم vocabulary ثابتة من domain: Reservation ليست Booking في class و Order في endpoint إذا الفريق يقصد نفس المفهوم. لكن لا تفرض نفس الاسم عبر bounded contexts مختلفة لو المعنى مختلف. Naming consistency تقلل translation cost.

04

Small Functions و Single Level of Abstraction

One coherent operation per function
Practical

الدالة الجيدة لها purpose واحد واضح، parameters قليلة، side effects معلنة، ومستوى abstraction متقارب. لا تقسم كل سطر إلى method؛ الهدف جعل flow مقروءًا. لو method فيها validation و SQL و email formatting و retry و mapping، غالبًا تجمع concerns مختلفة.

C#Before — mixed levels and side effects
public async Task ProcessAsync(Guid id)
{
    var order = await db.Orders.FindAsync(id);
    if (order == null) throw new Exception("Missing");
    if (order.Status != "Pending") throw new Exception("Bad status");
    order.Status = "Paid";
    await db.SaveChangesAsync();
    await smtp.SendMailAsync(order.Email, "Paid", "Your order is paid");
}
C#After — explicit intent and boundaries
public async Task MarkOrderPaidAsync(Guid id, CancellationToken ct)
{
    var order = await LoadPendingOrderAsync(id, ct);
    order.MarkPaid();
    await unitOfWork.SaveChangesAsync(ct);
    await outbox.AddAsync(OrderPaidMessage.From(order), ct);
}

الكود الثاني لا يوضح كل implementation، لكنه يعبر عن flow. الـ outbox يجعل notification delivery منفصلة عن DB transaction. لا تستبدل كل logic بأسماء methods فارغة؛ اجعل method boundaries تحمل معنى وتخفي تفاصيل مفيدة.

05

Comments vs Self-Explaining Code

Explain why, not what
Practical

Comment جيد يشرح لماذا قرار غير واضح أو workaround أو business constraint. Comment سيئ يعيد قراءة السطر: // increment count فوق count++. comments قد تصبح stale بعد refactor؛ الأفضل code واضح، ثم comment للسبب/السياق الذي لا يظهر من code.

لا تحذف comments التي توثق compliance/security constraints أو external quirks لمجرد أنها طويلة. انقلها إلى ADR/docs إذا كانت architecture decision. واحتفظ links للمصدر/issue عند workaround.

Comments و XML Docs و Architecture Decision Records

XML documentation مفيدة للـ public library APIs: purpose، parameter semantics، exceptions، thread-safety، lifetime، cancellation. لا تكتب comment يكرر اسم method. Architecture Decision Record (ADR) يوثق context، decision، alternatives، consequences، date/owner. ADR مناسب لقرار مثل اختيار SQL Server، refresh token rotation، modular monolith، أو cache consistency model.

وثيقة جيدة تشرح why/constraints، بينما code يوضح how. لو workaround مرتبط بـ provider bug، أضف issue/version link وشرط إزالة workaround. لا تعتمد على tribal knowledge في security/concurrency decisions.

06

Code Smells: إشارات تستحق التحقيق

Symptoms, not automatic verdicts
Deep dive
  • Long Method / Large Class: مسؤوليات كثيرة أو مستويات abstraction مختلفة.
  • Long Parameter List: مجموعة parameters تمثل concept واحدًا أو configuration object.
  • Primitive Obsession: strings/decimals تمثل email/money/quantity بلا type safety.
  • Feature Envy: method تستخدم بيانات object آخر أكثر من بياناتها.
  • Data Clumps: نفس مجموعة fields تظهر دائمًا معًا.
  • Shotgun Surgery: تغيير واحد يحتاج تعديل ملفات كثيرة.
  • Duplicate Knowledge: business rule واحدة مكررة في أماكن متعددة.
  • Boolean Blindness: calls مثل Process(true, false) غير مفهومة.
  • Speculative Generality: abstractions لاحتياجات مستقبلية غير مؤكدة.

Smell لا يعني refactor فورًا. قيّم frequency of change، bug history، test coverage، ownership و complexity. بعض duplication أقل ضررًا من abstraction مشتركة تربط modules مستقلة.

Boolean Blindness و Null Handling

Call مثل Export(true, false, true) لا توضح معنى flags. استخدم named arguments أو options/enum واضح. Boolean parameters قد تمثل أكثر من mode في method واحدة؛ افصل operations أو استخدم options record. كذلك null قد تعني not found أو unknown أو optional؛ وضح semantics بدل إرجاع null في كل مكان.

C#Replace ambiguous booleans with explicit options
public sealed record ExportOptions(
    bool IncludeArchived,
    bool IncludePayments,
    ExportFormat Format);

await exporter.ExportAsync(orderId,
    new ExportOptions(IncludeArchived: false,
                      IncludePayments: true,
                      Format: ExportFormat.Pdf), ct);

لا تنشئ options object لكل method فيها boolean واحد واضح؛ استخدم named argument عند الحاجة. الهدف أن call site يقرأ كجملة مفهومة.

Data Structures vs Objects

Object-oriented design يميل إلى objects تخفي state وتقدم behavior، بينما data structures تعرض data ويعمل عليها functions خارجية. DTO غالبًا data structure بلا business behavior، و domain entity object يحمي invariants. لا تجعل DTO rich domain object، ولا تجعل entity public bag of setters إذا rules مهمة.

اختيار الشكل يعتمد على use: API response تحتاج serialization واضح، query projection تحتاج data-only shape، aggregate يحتاج methods تمنع invalid state. محاولة جعل كل types objects غنية تزيد mapping/complexity، ومحاولة جعل كل شيء records بلا behavior تنقل rules إلى services عامة.

07

Extract Method و Introduce Parameter Object

Refactor in small safe steps
Deep dive

Extract Method يحول block له intent واضح إلى method باسم يعبر عنه. Introduce Parameter Object يجمع parameters مترابطة في type واضح، مع validation عند الإنشاء. لا تجمع parameters مختلفة فقط لتقليل signature؛ object يجب يمثل concept حقيقي.

C#Parameter object
public sealed record OrderSearchCriteria
{
    public Guid CustomerId { get; }
    public DateTimeOffset? From { get; }
    public DateTimeOffset? To { get; }
    public int PageSize { get; }

    public OrderSearchCriteria(Guid customerId,
        DateTimeOffset? from, DateTimeOffset? to, int pageSize)
    {
        if (from.HasValue && to.HasValue && to <= from)
            throw new ArgumentException("Invalid date range.");
        CustomerId = customerId;
        From = from; To = to;
        PageSize = Math.Clamp(pageSize, 1, 100);
    }
}

Parameter Object يقدر يحمل behavior مثل ApplyTo(query) لو ده يظل cohesive، لكن لا تحوله إلى God request object يجمع كل filters لكل screens.

Refactoring Catalog: Extract, Move, Replace, Introduce

Refactoringمتى تستخدمها؟ما الذي تراقبه؟
Extract Methodblock له intent واضح أو abstraction level مختلفلا تنتج methods بأسماء عامة أو parameters كثيرة
Move Methodmethod تستخدم data من collaborator أكثرراجع ownership والـ coupling
Extract Classclass تحمل responsibility ثانية متماسكةلا تفصل class صغيرة بلا change reason
Introduce Parameter Objectمجموعة inputs تمثل concept واحدًالا تجمع unrelated flags
Replace Conditional with Polymorphismvariation متكرر عبر typesلا تبنِ hierarchy ل switch ثابت صغير
Encapsulate Collectioncaller يغير collection ويتجاوز invariantsوفر read-only view و methods محددة
Replace Primitive with Value Objectprimitive تحمل meaning/validationلا تحول كل string إلى class
08

Replace Conditional with Polymorphism

Use only when variation is real
Practical

لو switch على نوع أو status يكرر نفس decision في أماكن كثيرة، polymorphism/Strategy قد يقلل duplication. لكن switch صغير على enum ثابت قد يكون أوضح. refactor عندما تضيف type جديدًا يفرض تعديلات متعددة أو عندما لكل branch behavior مستقل ومعقد.

C#Before and after concept
// Before: every new shipping mode changes this method.
var cost = mode switch
{
    ShippingMode.Standard => 50m,
    ShippingMode.Express => 100m,
    _ => throw new NotSupportedException()
};

// After: select an IShippingCostPolicy implementation.
var cost = shippingPolicy.Calculate(order, destination);
09

Characterization Tests قبل Refactoring

Capture existing behavior first
Deep dive

في legacy code، قد لا تعرف behavior بالكامل أو قد يكون فيه quirks يعتمد عليها users. Characterization test تسجل ما يفعله النظام حاليًا قبل التغيير، حتى لو behavior غير مثالي. بعد refactor، قرر intentional behavior changes في tests منفصلة. ده يمنع إصلاحًا غير مقصود أثناء تحسين structure.

لو code لا يمكن اختباره بسبب dependencies مباشرة، ابدأ باستخراج seam صغير حول clock/file/network، أو اعمل integration test على boundary. لا تعيد كتابة module كاملة قبل أن تملك feedback loop.

10

Boy Scout Rule و Code Review Checklist

Leave touched code better
Practical

Boy Scout Rule: اترك المكان أنظف مما وجدته، لكن بحجم تغيير آمن. أصلح اسمًا مضللًا أو duplicate صغيرة في المنطقة التي تعمل بها، ولا تحول bug fix صغيرًا إلى rewrite شامل. في code review راجع intent، correctness، security، concurrency، performance، tests، logging، API compatibility و migration impact.

  • هل الاسم يوضح business intent؟
  • هل method لها side effects واضحة؟
  • هل null/empty/boundary cases محسوبة؟
  • هل error handling لا يبتلع failure؟
  • هل permissions/tenant checks موجودة؟
  • هل DB calls/pagination/index usage معقولة؟
  • هل tests تثبت behavior و failure paths؟
  • هل abstraction أضافت قيمة أم مجرد طبقة؟

Code Review عملي: correctness قبل style

ابدأ بمراجعة correctness/business rules، ثم security/authorization، concurrency/transactions، performance/data access، error handling/logging، tests، ثم naming/style. لا تستهلك معظم review في braces/formatting؛ formatter/analyzers تتولى style. اسأل عن edge cases و rollback/compatibility.

Reviewer لا يفرض personal preference كأنه rule. اطلب rationale عند abstraction كبيرة، وقدم suggestion محددة مع سبب. Author يشرح intent ويقبل التغيير عندما يحسن readability/correctness. الهدف codebase consistent، مش انتصار أسلوب شخصي.

Final Maintainability Review قبل Merge

قبل merge، تأكد أن اسم class يصف responsibility، وأن method لا تخفي side effects، وأن null/error semantics واضحة، وأن cancellation ينتقل إلى IO، وأن logs لا تحتوي secrets أو personal data. راجع boundaries مع API contracts و database migrations و message schemas. الكود النظيف لا يقتصر على naming؛ هو code يمكن فهم أثر تغييره واختباره وتشغيله.

اطلب من reviewer أن يقرأ call path من endpoint إلى use case إلى persistence/external adapter. إذا احتاج معرفة تفاصيل implementation كثيرة لفهم feature واحدة، فقد تكون boundary أو ownership غير واضحة. استخدم ADR عندما يكون القرار له تكلفة طويلة الأجل، واستخدم comments لشرح why/constraint لا لإعادة كتابة الكود باللغة الإنجليزية.

11

Technical Debt و Static Analysis

Make quality visible in the workflow
Deep dive

Technical debt قرار واعٍ أو غير واعٍ يؤجل تكلفة اليوم إلى المستقبل. بعض الدين مقبول لو trade-off واضح وموثق بمالك/سبب/موعد مراجعة. الدين الخطر هو hidden complexity بلا owner، مثل migrations غير آمنة، dependencies قديمة، flaky tests، أو duplicated authorization logic.

Roslyn analyzers و ‎.NET analyzers تكشف patterns ومشاكل محتملة وقت build/IDE. SonarQube/SonarCloud يضيف quality gates و security/static analysis. Formatter/editorconfig يحافظ على style consistency. الأدوات لا تفهم business semantics بالكامل؛ اضبط severity، قلل false positives، وراجع findings بدل تجاهلها كلها.

XML.editorconfig excerpt
root = true

[*.cs]
dotnet_analyzer_diagnostic.severity = warning
csharp_style_namespace_declarations = file_scoped:warning
csharp_style_var_for_built_in_types = true:suggestion
csharp_style_var_when_type_is_apparent = true:suggestion

في CI، شغل format verification و build analyzers/tests. لا تجعل formatting changes الضخمة تختلط مع business refactor؛ افصلها لتسهيل review و blame.

Metrics: Complexity و Duplication و Maintainability

Cyclomatic complexity تقيس عدد مسارات القرار تقريبًا؛ ارتفاعها في method قد يشير إلى branches كثيرة، لكنه لا يحدد جودة design وحده. Cognitive complexity تحاول قياس صعوبة الفهم. Duplication metrics تكشف نسخ code، لكنها لا تعرف هل النسخ تمثل نفس business knowledge. Maintainability index/quality gate مؤشرات، لا أهداف مستقلة.

استخدم metrics لتحديد hotspots ثم راجعها يدويًا. ركز على files كثيرة التغيير، bugs متكررة، dependencies كثيرة، tests ضعيفة، أو high complexity في security/financial logic. لا refactor file لمجرد تجاوز رقم arbitrary إذا behavior واضح ومخاطر التغيير أعلى.

قياس Maintainability بدون Worship للـ Metrics

Cyclomatic complexity، cognitive complexity، coupling، code churn، test coverage، duplication، و change failure rate كلها إشارات مفيدة، لكنها لا تقيس جودة التصميم وحدها. method فيها switch صغير واضح قد تحصل على complexity أعلى من سلسلة callbacks يصعب تتبعها. Coverage مرتفعة لا تثبت أن assertions تختبر business outcomes. خذ metric كإشارة لتحديد مكان review، ثم اقرأ code وافهم context.

راقب hotspots: الملفات التي تتغير كثيرًا مع defects متكررة، modules التي تحتاج تعديلات كثيرة لكل feature، أو tests الهشة التي تفشل عند refactor غير مؤثر. هذه قد تشير إلى boundary غير مناسبة أو ownership غير واضح. لا تضع target مثل «كل methods أقل من 10 أسطر»؛ هذا يشجع تفتيت الكود وإخفاء flow في عشرات helpers.

Definition of readable code: زميل جديد يستطيع فهم intent، tracing، error behavior، side effects، والحدود المهمة دون فتح عشرين ملفًا. naming و small functions تساعد، لكن architecture والـ tests والـ observability هي التي تكمل الصورة.

12

Refactoring Workflow عملي

A repeatable safe sequence
Practical
  1. حدد smell وسبب التغيير، واكتب behavior المطلوب الحفاظ عليه.
  2. أضف characterization/unit/integration test حسب boundary.
  3. نفذ refactor واحدًا صغيرًا: Rename، Extract Method/Class، Parameter Object، Move Method.
  4. شغل tests و static analysis بعد كل خطوة.
  5. راجع diff للتأكد من عدم تغير public behavior أو API contract.
  6. قس الأداء لو التغيير مس query/allocation/concurrency.
  7. وثّق trade-off أو ADR لو القرار معماري طويل الأثر.

لا تستخدم «Clean Code» ذريعة لتغيير كل شيء. الهدف تقليل تكلفة التغيير القادم مع الحفاظ على correctness. أفضل refactor غالبًا صغير، قابل للمراجعة، وله test تثبت أن السلوك لم يتغير.

Refactoring Playbook: من Code Smell إلى تغيير آمن قابل للمراجعة

Refactoring هو تغيير internal structure مع الحفاظ على observable behavior. لا تبدأ بإعادة كتابة module بالكامل. اختَر smell محددًا، حدّد behavior الذي يجب أن يظل كما هو، واكتب characterization tests قبل تحريك الكود إذا كانت التغطية ضعيفة. بعد ذلك نفذ خطوة صغيرة، شغّل الاختبارات، راجع diff، ثم commit.

Code smellRefactoringعلامة نجاح
Long methodExtract Method باسم يعبر عن intentالخطوات أصبحت مقروءة دون إخفاء flow
Repeated conditionalExtract policy/Strategy عند وجود محور تغييراختلاف السلوك معزول والاختبارات مستقلة
Primitive obsessionValue Object عند وجود invariant أو semanticsinvalid value أصعب في التمثيل
Feature envyMove Method للمالك الصحيح للبياناتلا توجد getters متسلسلة أو coupling زائد
Shotgun surgeryاجمع behavior المتماسك خلف boundaryالتغيير الواحد لا يلمس ملفات غير مترابطة
Boolean parameterNamed methods أو explicit options typecall site يوضح intent
C#Replace boolean mode with an explicit operation
// Ambiguous: what does true mean at the call site?
await reportExporter.ExportAsync(report, true, ct);

// Intent is visible and compiler helps discover valid operations.
await reportExporter.ExportPdfAsync(report, ct);
await reportExporter.ExportCsvAsync(report, ct);

لا تطبق Extract Interface أو Strategy لمجرد وجود smell شكلي. اسأل: هل يوجد محور تغيير؟ هل يوجد consumer يحتاج contract مستقل؟ هل abstraction ستقلل المعرفة المطلوبة أم تضيف indirection؟ لا تستخرج interface من كل class لمجرد mocking؛ استخدم real collaborators أو fake عند الحاجة، وراقب حدود النظام التي تستحق substitution.

قبل refactor في نظام production، راجع compatibility: public API، serialized JSON، database schema، event contracts، ordering، exception semantics، cancellation، transaction boundaries، و performance. لو schema تتغير مع deployment متدرج، استخدم expand/contract: أضف الشكل الجديد بشكل متوافق، انقل القراءة/الكتابة تدريجيًا، ثم احذف القديم بعد التأكد من كل instances.

Definition of Done: behavior tests خضراء، لا regression في authorization أو concurrency، analyzers/formatters تعمل، benchmark أو query count لا يتدهور في المسارات الحساسة، و ADR محدث لو القرار المعماري تغير. refactor الجيد يجعل التغيير القادم أسهل، لا يجعل عدد interfaces أكبر فقط.

مثال Refactoring متدرج: فصل Pricing عن Checkout مع الحفاظ على السلوك

افترض أن CheckoutService تحسب subtotal والخصم والضريبة والإجمالي ثم تحفظ الطلب. لا تستخرج خمس classes دفعة واحدة. أولًا اكتب tests للحالات الحالية: عضو عادي، VIP، سلة فارغة، خصم أكبر من subtotal، وتقريب العملة. ثبّت rounding rule لأن نقل العمليات أو تغيير ترتيب الضرب والجمع قد يغير النتيجة المالية.

ثانيًا استخرج calculation pure function لا تنفذ IO. ثالثًا سمّ النتائج بـ PricingBreakdown بدل tuple غامض. رابعًا اجعل Checkout تنسق payment/persistence فقط. بعد كل خطوة شغّل tests وقارن outputs القديمة والجديدة. لا تغير discount policy في نفس commit؛ افصل refactoring عن feature change حتى يسهل تحديد regression.

C#Explicit calculation result
public sealed record PricingBreakdown(
    decimal Subtotal, decimal Discount, decimal Tax, decimal Total);

public static class OrderPricing
{
    public static PricingBreakdown Calculate(
        decimal subtotal, decimal discountRate, decimal taxRate)
    {
        if (subtotal < 0) throw new ArgumentOutOfRangeException(nameof(subtotal));
        if (discountRate is < 0 or > 1) throw new ArgumentOutOfRangeException(nameof(discountRate));
        if (taxRate is < 0 or > 1) throw new ArgumentOutOfRangeException(nameof(taxRate));

        var discount = decimal.Round(subtotal * discountRate, 2,
            MidpointRounding.AwayFromZero);
        var taxable = subtotal - discount;
        var tax = decimal.Round(taxable * taxRate, 2,
            MidpointRounding.AwayFromZero);
        return new(subtotal, discount, tax, taxable + tax);
    }
}

الكود يوضح pure calculation، لكنه لا يقرر وحده هل tax محسوبة على shipping أو discounts، ولا يحدد currency precision لكل عملة. هذه business rules يجب أن تكون explicit في domain requirements، لا افتراضات مخفية داخل helper. Value Object مثل Money قد يكون أنسب عندما توجد currencies متعددة.

في النهاية قارن behavior، exceptions، rounding، logging، database writes، وعدد external calls. لو tests لم تغطِ السلوك القديم، احتفظ characterization tests فترة حتى يصبح contract الجديد موثقًا. هذا يجعل refactor قابلًا للمراجعة ويمنع أن يتحول تحسين readability إلى تغيير مالي غير مقصود.

Refactoring Safety: Behavior Preservation و Small Commits

Refactor آمن غالبًا يبدأ بـ test، ثم rename/extract/move، ثم tests، ثم commit صغير. لا تغير public API وال database schema وال business behavior في نفس commit إلا لو لازم. لو migration مطلوبة، استخدم expand/contract. لو code legacy لا يوجد له tests، أضف characterization test حول behavior observable قبل التغيير.

راجع diff: هل زادت allocations؟ هل تغير query count؟ هل أصبحت method async بلا داعٍ؟ هل تغير ordering؟ هل تغير exception type؟ Refactor قد يحافظ على output في happy path لكنه يغير concurrency/error semantics؛ لذلك اختبر failure paths.

13

اختبر فهمك

Knowledge check
Practical
هل Refactoring يغير behavior؟
لا؛ refactoring يغير internal structure مع الحفاظ على externally observable behavior. feature change شيء منفصل.
متى نستخدم Characterization Tests؟
قبل تعديل legacy behavior غير مفهوم بالكامل لتسجيل ما يفعله النظام الحالي.
هل كل duplicate code يجب توحيدها؟
لا؛ لو النسخ تمثل knowledge/أسباب تغيير مختلفة، التجميع قد يزيد coupling.
ما فائدة Parameter Object؟
تمثيل مجموعة parameters مترابطة كـ concept واضح مع validation، وليس مجرد تقليل عدد arguments.
هل static analysis بديل عن code review؟
لا؛ يكشف أنماطًا ومخاطر آلية، لكنه لا يفهم كل business/security context.
14

Error Design: Exceptions vs Result

Do not use exceptions for every branch
Deep dive

Exception مناسبة لظروف استثنائية أو failure غير متوقع في flow العادي، مثل database unavailable أو corrupted state. Expected business outcomes مثل insufficient stock أو duplicate email قد تكون Result/typed error أكثر وضوحًا. لا تستخدم exception كـ control flow في loop عالي التكرار، ولا ترجع Result لكل شيء إذا exceptions الحالية أبسط.

لا تبتلع exception وتعيد default value؛ ده يخفي defect. أضف context عند rethrow من غير فقد stack trace، واستخدم throw; داخل catch بدل throw ex;. لا تعرض exception details للعميل. Error contract في API يجب يظل stable حتى لو implementation exception تغيرت.

15

Immutability و Side Effects و Functional Core

Make state changes explicit
Deep dive

Immutable values تقلل shared-state surprises، خصوصًا في concurrent systems. Pure function ترجع output من input من غير side effects، فتكون سهلة الاختبار. Functional Core / Imperative Shell يعني business calculations قدر الإمكان pure، والـ shell يتعامل مع DB/network/time. لا تحاول تجعل كل شيء functional؛ استخدم الفكرة لعزل deterministic logic.

Side effects مثل sending email، writing DB، publishing event يجب تكون واضحة في method names/boundaries. لا تجعل property getter ينفذ database query أو network call. لا تجعل method اسمها CalculateTotal تعدل inventory. وضوح side effects يجعل retries والتزامن أسهل للفهم.

16

Clean Code في Async و Concurrent Systems

Make cancellation, ownership and side effects visible
Deep dive

في async code، أسماء methods يجب توضح أنها async بـ Async suffix، و CancellationToken يمر عبر call chain. لا تستخدم fire-and-forget task من غير owner/error handling. لا تشارك mutable List/Dictionary بين threads من غير synchronization. لا تعمل async void إلا event handlers. لا تستخدم lock حول await.

Resource ownership واضح: من يفتح Stream؟ من يتخلص منه؟ هل method تأخذ ownership أم caller؟ استخدم await using للموارد async disposable. لا ترجع enumerable مرتبط بـ DbContext بعد إغلاق scope؛ materialize أو stream ضمن lifetime واضح.

17

Clean API Design: Parameters و Return Types

Make invalid usage harder
Practical

Prefer explicit types: Money بدل decimal غير محدد currency، EmailAddress بدل string لو validation مهمة، DateRange بدل from/to منفصلين إذا لهما invariant. Return type يوضح semantics: Task<Order?> يعني absence محتمل، Result يوضح expected errors، collection فارغة تختلف عن null. لا تستخدم boolean return لو caller يحتاج سبب الفشل.

لا ترجع object أو dynamic بلا سبب. لا تجعل method تقبل عشرين parameter optional؛ استخدم request/criteria object عندما تمثل concept. لا تخلط input DTO مع entity لأن API contract و domain lifecycle مختلفان.

18

Readable Code و Performance: لا تخفي التكلفة خلف Syntax جميلة

Clarity includes allocation, query count and I/O
Deep dive

الكود القصير ليس بالضرورة كودًا أسرع أو أوضح. LINQ chain جميلة قد تنفذ query لكل row إذا كان هناك lazy loading، و ToList() المبكر قد يسحب ملايين records للذاكرة، و Task.WhenAll على آلاف العمليات قد يضغط database connection pool. اقرأ code مع فهم تكلفة التنفيذ: allocations، enumeration، network round trips، locks، query plan، cancellation، والـ backpressure.

لا تحسن performance بالتخمين. قِس baseline، حدد bottleneck، غيّر نقطة واحدة، ثم قارن p50/p95 latency و throughput و allocations و DB query count. حافظ على readability مع تسمية intent وتحديد boundaries. لو optimization جعل algorithm معقدًا، اشرح invariant والسبب في comment/ADR، واكتب benchmark أو regression test يحمي المكسب.

مثال: بدل foreach يستدعي repository لكل product في order (N+1)، اجمع IDs ثم نفذ bulk query واحدة، وابنِ dictionary للـ lookup. لكن لا تحول كل flow إلى batch إذا كان العدد صغيرًا والوضوح أهم. الاختيار مرتبط بحجم البيانات والـ latency budget والقياس.

↗

المراجع والقراءة الإضافية

References & further reading

الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

مصادر تعليمية ومتقدمة — Third-party & advanced reading

خريطة التغطية: 13 عنصر من الـ Roadmap ومكان شرحه في الدرس
New sectionNaming§01
New sectionSmall functions§01
New sectionComments vs self-explaining code§01
New sectionCode smells§01
New sectionExtract Method§07
New sectionIntroduce Parameter Object§07
New sectionReplace Conditional with Polymorphism§06
New sectionCharacterization tests before refactoring§09
New sectionBoy Scout rule§01
New sectionCode review checklist§01
New sectionTechnical debt§01
New sectionStatic analysis: Roslyn analyzers, SonarQube§10
New sectionConsistent formatting§10

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

محتويات الدرس