لقد صادفت وثيقة تحتوي على قواعد وتوصيات حول عملية مراجعة التعليمات البرمجية داخل الشركة. قررت أنه يجب مشاركة هذه المعلومات المفيدة مع العالم الخارجي. بمباركة
المؤلف ، أنشر العمل.
معظم هذه القواعد استشارية في طبيعتها ويجب أن تسترشد في المقام الأول بالحس السليم ، وليس مراعاة عمياء.
أحكام عامة
- في hh.ru ، تتم المراجعة بتنسيق طلب السحب على Github.
- طلبات المراجعة والسحب مطلوبة ، حتى إذا تم تغيير سطر واحد أو حرف واحد في التعليمات البرمجية في إطار المهمة.
- يجب أن يكون لكل مهمة مراجع واحد مسؤول على الأقل ، ويتم الإشارة إليها في المهمة كمراجع وهي مسؤولة عن التعليمات البرمجية ، مثل المؤلف. لا يحظر ويشجع على المشاركة في استعراض الآخرين.
- تقع مسؤولية تنفيذ المهمة من خلال المراجعة على عاتق كاتب المهمة.
- يجب أيضًا معاينة أي تغييرات بعد المراجعة ، مثل المراجعات أثناء الاختبار.
أهداف المراجعة
- نشر الخبرة والمعرفة بين المطورين.
- دعم المبدأ - يجب ألا تؤدي التغييرات إلى تفاقم الرمز الحالي ، بل يجب تحسينه.
- تصحيح الأخطاء في المنطق والأخطاء المتعلقة بالأمان ، والتعامل الصحيح مع الاستثناءات.
- تحسين جودة التعليمات البرمجية وقابلية الصيانة وهندسة المشروع.
- تحسين قراءة التعليمات البرمجية.
- تحسين تغطية الاختبار والاختبار على المستوى الصحيح.
- تحسين التوثيق.
- الامتثال للتغييرات مع متطلبات المهمة.
- منع الدين الفني أو الضريبة الفنية.
- التصميم المدروس لواجهة برمجة التطبيقات ، حيث أن API هي أي وحدة ذات واجهة خارجية. على سبيل المثال ، أن المورد في الخدمة لديه عنوان URL مدروس جيدًا ، وتنسيق JSON مناسب ، ورموز الاستجابة الصحيحة في حالات مختلفة ، وما إلى ذلك.
- التاريخ الصحيح للالتزامات في Gita ، مع الرسائل التي تعكس جوهر الرسالة ، بدون عمليات مؤقتة.
التحضير للمراجعة
- قبل نشر طلب سحب ، اقرأ التعليمات البرمجية 2-3 مرات: مع احتمال كبير ، ستجد نفسك هناك أخطاء ، مما سيوفر الوقت للمراجع. تحقق من عدم وجود أخطاء يمكن اكتشافها تلقائيًا - أخطاء نمط التعليمات البرمجية ، اختبارات إسقاط. تأكد من أن الشفرة لا تحتوي على تعليقات مؤقتة ورمز تصحيح الأخطاء ، وتحقق أيضًا من أن الشفرة تتطابق مع أدلة النمط المقبولة.
- إذا قمت بإنشاء طلب سحب في عملية العمل على مهمة ، فاكتب "[WIP]" في العنوان وضع علامة "العمل قيد التقدم". عند الانتهاء من العمل ، قم بإزالة العلامات وإبلاغها في تعليق منفصل حتى تعرف الأطراف المعنية أنه يمكن عرض الرمز.
- كن مستعدًا لإظهار المراجع عرضًا مصغرًا للمهمة.
- أعط أجزاء صغيرة من التعليمات البرمجية للمراجعة. 200-300 خطوط التغيير - الحد لمراجعة فعالة.
- قم بإجراء تغييرات مستقلة في عمليات منفصلة.
- وصف الانتهاكات برسائل قصيرة وغنية بالمعلومات.
- قم بإعادة الهيكلة كالتزام منفصل ، من الأسهل رؤية التغييرات في المنطق ، جوهر المهمة.
- تنسيق التعليمات البرمجية كالتزام منفصل قبل التغييرات الرئيسية ، أو حتى كطلب سحب منفصل.
- لا ترتكب تغييرات طفيفة. على سبيل المثال ، إضافة فواصل أسطر في ملف لم تقم بتغيير أي شيء آخر فيه.
- في عنوان طلب السحب ، صف بإيجاز وجوهر المعلومات جوهر التغييرات.
- صف المشكلة والحل في طلب السحب. وصف الحلول البديلة وسبب اختيار الحل الحالي. إذا كانت التغييرات تتعلق بالواجهة ، أرفق لقطات الشاشة "قبل" و "بعد".
- في طلب السحب ، أعط رابطًا للمهمة ، وفي المهمة رابطًا لطلب السحب.
- من المفيد أحيانًا مناقشة الحل المختار مع المراجع قبل كتابة الرمز. سيساعد ذلك على إيجاد أفضل حل للمشكلة وتبسيط عملية المراجعة.
اختيار المراجع
- أعط مهمة المراجعة إلى أخصائي في المجال ذي الصلة.
- إذا عملت عدة أوامر مع بعض التعليمات البرمجية ، فمن المفيد تحديد مراجع من فريق آخر لنشر المعرفة.
- قد لا يكون ضابط المراقبة المراجع المسؤول ، ولكن قد يشارك في عملية المراجعة.
- لا تعطي جميع مهامك للمراجعة لنفس الأشخاص - اطلب مراجعات من أشخاص مختلفين.
- إذا كانت المشكلة تتضمن جزءًا غير عادي من التعليمات البرمجية يفهمه شخص معين ، فقم بإظهار التغييرات له ، بغض النظر عن هوية المراجع المسؤول. تذكر أيضًا أن كل مستودع لديه مشرفين ، فهم يعرفون المزيد عن هذا الرمز ويشرفون على التطوير.
- يتم اختيار باقي المراجع بشكل تعسفي باتفاق الطرفين. استخدم التوصيات على github بناءً على "اللوم" على الشفرة المتأثرة لمساعدتك في الاختيار.
- بعد اختيار المراجع ، حدده كمعين له في طلب السحب. قائمة بكل طلبات السحب التي تم تخصيصها لك.
عملية المراجعة ، عام
يشير إلى كل من مؤلف الشفرة والمراجع.
- كل الكود شائع ، ولا توجد مفاهيم مثل "الكود الخاص بي" أو "الكود الخاص بك". هذا يعني أن كل مطور مسؤول عن أي سطر من التعليمات البرمجية ، وليس فقط الشخص الذي كتب هذا السطر.
- اخلق جوًا من التفاهم المتبادل ، وكن مهذبًا وودودًا ، واحترم بعضكما البعض ، ولا تفرض رأيك. استمع إلى رأي الخصم ولا تقف على موقفك المبدئي. لا تحول المراجعة إلى تجربة سلبية للزملاء.
- اطرح أسئلة إذا كان هناك شيء غير واضح. حجة وتحديد الأسئلة والأجوبة. قد لا يكون واضحًا لمؤلف الشفرة ما هو المقصود بالسؤال "لماذا هذا؟" ، لكن المراجع لا يفهم حجة الإجابة "لا أوافق".
- لا تمد عملية المراجعة ، وفر الوقت ، واستجب سريعًا للتعليقات ، وناقشها شفهيًا ، ولا تثير مناقشات مطولة ولا تولد "holivars". إذا لم تتمكن من الوصول إلى إجماع سريع ، فاطلب المساعدة من زملائك أو مشرفك أو مدير المجال الوظيفي.
- إذا لم تكن المهمة على سطرين ، اقضي 10-15 دقيقة مع المراجع في مراجعة كود مشتركة ، فمن المفيد القيام بذلك حتى قبل إنشاء طلب سحب. ناقش جوهر المهمة والحل ، وانظر كيف كانت وأصبحت في بيئة عمل. سيساعد هذا المراجع على الغوص بشكل أفضل في سياق المهمة. ستظل معظم التعليقات غير مكتوبة ، مما سيوفر الوقت للجميع.
- بعد مناقشة شفوية ، قم دائمًا بوصف القرار المتخذ وأسبابه في طلب السحب. تقع مسؤولية الوصف على عاتق مؤلف الرمز.
- إذا كانت الشفرة تحتوي على نفس النوع من الأخطاء ، فيجب على المراجع التركيز على انتباه مؤلف الشفرة في التعليق الأول أو الثاني دون التعليق على كل إدخال ، ويجب على المؤلف تحليل الشفرة لنفس النوع من الأخطاء قبل نشر التصحيح.
- الثناء على قرارات المؤلف الناجحة واقتراحات المراجع.
- اترك التعليقات على التغييرات في طلب السحب نفسه ، وليس على عمليات التنفيذ الفردية. وبالتالي ، ستكون جميع المراسلات في مكان واحد ، بما في ذلك بعد rebase.
- الرد على التعليقات في نفس سلاسل المناقشة التي بدأت فيها. إذا كان التعليق يشير إلى طلب السحب بالكامل أو عدة تعليقات في نفس سلسلة المحادثات ، فاقتبس التعليق الذي تم التعليق عليه. للتبديل من بريد إلكتروني إلى سلسلة مناقشة قديمة ، بدلاً من رابط "عرضها على GitHub" ، استخدم رابط "في المسار / إلى / ملف".
- إذا تم اتخاذ أي قرارات أساسية أثناء عملية المراجعة من وجهة نظر معايير التشفير أو الاتفاقيات الرسمية الأخرى ، فإن مؤلف الشفرة ملزم بتدوين هذه القرارات في الوثائق ذات الصلة.
- لا تتعلق المراجعة بالشفرة فحسب ، بل بالمهمة بأكملها. لا تعامل المتطلبات في المهمة أو التخطيطات على أنها الحقيقة المطلقة - الجميع يرتكب أخطاء ولا يمكن لأحد أن يأخذ في الاعتبار جميع الفروق الدقيقة. نظرة جديدة واقتراحات معقولة ستفيد المنتج فقط.
مراجعة العملية بواسطة مؤلف الكود
- لم تكتمل المهمة حتى اجتازت المراجعة والاختبار والافراج عن "همز".
- الرد على جميع تعليقات المراجع ، لا تترك التعليقات دون إجابة ، بغض النظر عما إذا كنت قد قبلتها أم لا.
- فكر في الأسئلة التي تنشأ أو قد تنشأ أثناء المراجعة. ربما يفتقد قسم الرمز تعليقًا ، أو من الأفضل كتابة الرمز بشكل أكثر وضوحًا.
- لا تصحح عمليات التنفيذ الحالية باستخدام أمر gend --amend ؛ بدلاً من ذلك ، قم بإجراء تغييرات على أنها عمليات منفصلة ، واحدة لكل إصلاح. يؤدي تصحيح عمليات التنفيذ الحالية إلى تعقيد عملية المراجعة إلى حد كبير ، حيث يجب عليك مراجعة جميع التعليمات البرمجية مرة أخرى.
- بعد إضافة التزام جديد إلى طلب السحب ، اكتب في تعليق منفصل ملخصًا بالتغييرات بحيث تكون الأطراف المعنية في معرفة. ينطبق هذا على التصحيحات أثناء المراجعة ، وكذلك التصحيحات أثناء الاختبار.
- بعد المراجعة ، قبل إرسال المهمة للاختبار ، أعد كتابة محفوظات الأوامر (git rebase - interactive) ، وإجراء تصحيحات على عمليات التنفيذ الفردية وحذف عمليات التنفيذ المؤقتة. تحقق من خيار --autosquash لتبسيط العملية.
عملية المراجعة من قبل المعلقين
- إذا كنت مشغولاً في وقت طلب المراجعة ، فأخبرني بالضبط متى ستبدأ المراجعة.
- لا تطلب ، ولكن اقترح إجراء تغييرات.
- علق على الكود وليس الشخص الذي كتبه.
- أنت تتحمل المسؤولية عن الشفرة المكتوبة ، وتتعامل مع المراجعة وفقًا لذلك ، ولكن هذا لا يعني أن مؤلف الشفرة يجب أن يلتزم تمامًا بجميع متطلباتك. تذكر أن العديد من الأشياء يمكن القيام بها بطرق مختلفة.
- اتبع أهداف المراجعة واقترح تعديلات جوهرية. لا تصر على التغييرات غير الحرجة. وضح أهمية التصحيحات في التعليق.
- إذا وجدت مشكلة خطيرة ، أوقف المراجعة مؤقتًا وانتظر حتى يقوم المؤلف بإصلاحها. على الأرجح ، بعد التصحيح سيكون لا يزال من الضروري إعادة النظر.
- انتبه ليس فقط لما تم تغييره ، ولكن أيضًا لما لم يتغير. ابحث عن الكاتب وأظهر الكود الذي كان يجب تغييره ، ولكن لم يتم تغييره (عمليات الاستيراد المنسية أو الفئات غير المستخدمة ، باستخدام التعليمات البرمجية المعاد صياغتها في مكان آخر ، إلخ).
- بعد إجراء تغييرات بواسطة مؤلف الشفرة ، راجع التصحيحات وراجع طلب السحب بالكامل مرة أخرى. ربما ، رهنا بالتصحيحات ، سيكون لديك تعليقات أو أسئلة جديدة.
- لا تضيع الوقت في مراجعة التعليمات البرمجية التي لم تتغير كجزء من المهمة. يعتبر تخصيص جزء من التعليمات البرمجية في دالة تغييرًا. لا يعتبر تغيير الرمز "كما هو" تغييرًا. يتم إصلاح التعليمات البرمجية في الملف المتأثر وفقًا لتقدير المؤلف.
- لا يقوم المراجع بتحرير الكود في الفرع بشكل مستقل ، لأنه يريده كثيرًا أو أسهل. يتم إجراء التغييرات من قبل مؤلف الكود.
- إذا قمت بإجراء مراجعة ، فحاول ألا تؤخر أو تنتقل إلى مهام أخرى على حساب التيار
المواد المستخدمة والروابط ذات الصلة
PS شارك القواعد والتوصيات وحالات المستخدم المفيدة حول عملية المراجعة في التعليقات