تنظيف مقتطف PHP

لماذا يساعد التنسيق القارئ

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

قبل وبعد

الأصل، منسوخ من سجل:

<?php function total($items){$sum=0;foreach($items as $item){$sum+=$item["price"];}return $sum;}

بعد التنظيف مع 4 مسافات:

<?php function total($items)
{
    $sum=0;
    foreach($items as $item)
    {
        $sum+=$item["price"];
    }
    return $sum;
}

قائمة قصيرة قبل النشر

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

ما الذي لا تفعله هذه الأداة

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

أين تفيد هذه الأداة

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

في كل حالة يرى القارئ البنية أولًا ثم المشكلة، وهذا هو الترتيب الذي تريده.

الحفاظ على صدق المقتطف

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