افتح الـ PR الذي لم يسبق للمراجع أن اطلع عليه بعد

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

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

أدركت أنني قد فعلت ذلك بشخص آخر من قبل.

عندما تكتب الكود، تكون أنت حاملًا لكل السياق. أنت تعرف لماذا قمت بتقسيم الوحدة. أنت تعرف ما الذي حاولت القيام به أولاً. أنت تعرف الأجزاء التي تشعر بعدم اليقين تجاهها.

معظم الناس يكتبون الأوصاف لأنفسهم. يكتبون "Refactored service layer" أو "Fixed auth module". هذه أوصاف لأشخاص يعرفون السياق بالفعل.

الوصف الجيد هو للشخص الذي لا يعرف شيئًا.

الوصف ليس مجرد ملخص. إنه اختبار. إذا لم تتمكن من شرح عملك، فإن عملك ليس جاهزًا.

أستخدم الآن هيكلًا مكونًا من ستة أجزاء لكل PR غير بسيط:

• القصد (Intent): اشرح سبب وجود هذا الـ PR والمشكلة التي يحلها. إذا لم تتمكن من كتابة ذلك، فتوقف. الـ PR ليس جاهزًا. • التغييرات الرئيسية (Major changes): اذكر القرارات التي تؤثر على البنية (architecture) أو السلوك الحالي. • التغييرات الثانوية (Minor changes): اذكر عمليات التنظيف وإعادة التسمية. اجعلها منفصلة عن التغييرات الهيكلية. • التأثير (Impact): اذكر الأنظمة التي يمسها هذا التغيير. قدم خريطة لنطاق التأثير (blast radius). • الأدلة (Evidence): اذكر ما قمت بتشغيله وما هي الاختبارات التي اجتزتها. قدم دليلاً على أنك قمت بالعمل. • الشكوك (Uncertainties): اذكر ما لست متأكدًا منه.

عندما تعترف بالشكوك، فإنك تساعد المراجع. سيعرف أين ينظر بدقة. لن يضيع وقته في الأجزاء التي تعمل بشكل جيد.

إذا لم تتمكن من تسمية شكوكك، فأنت لم تفكر بعمق كافٍ في الكود الخاص بك.

الوصف هو الخطوة الأخيرة قبل أن تقرر ما إذا كان يجب فتح الـ PR من الأساس.

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

اكتب للمراجع الذي لم يسبق له رؤية الكود الخاص بك بعد. اكتب كما لو أنك لن تكون موجودًا للإجابة على الأسئلة. اكتب كما لو كنت تقرأه بعد ثلاثة أيام دون أي ذاكرة عن العمل.

إذا كان الوصف متماسكًا، فإن الـ PR جاهز.

Source: https://dev.to/jeelvankhede/open-the-pr-your-reviewer-has-not-met-yet-4gfe

Optional learning community: https://t.me/GyaanSetuAi