أفضل ممارسات مراجعة الرموز البرمجية

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

المراجع يستفيدون من رؤية مناهج مختلفة لحل المشكلات أثناء العمل. كما أنهم سيحسنون مهاراتهم في قراءة الرموز، وهو أمر مهم للغاية عند الغوص في مكتبة يجري تقييمها لاستخدامها في المشروع. مراجعة الكود هي أيضًا فرصة تعلم للمراجع بقدر ما هي فرصة تعلم للمؤلف: قد يتعلمون حيلًا جديدة أيضًا.

إن الفريق ككل، لأن مراجعة حل مشكلة معينة تتطلب فهم المشكلة على الأقل على مستوى عالٍ من التجريد. وهذا يساعد على هدم أي صوامع معرفية عرضية قد تحدث في الفريق. كما أنه سيزيد أيضًا من "عامل الحافلات": نظرًا لأن شخصين على الأقل (ويفضل أكثر) على علم بتغيير معين، فإن هناك احتمال أقل لحدوث موقف لا يعرف فيه أحد في الفريق كيفية تحديث وحدة معينة، أو سبب حدوث خطأ معين.

العميل الاستفادة من التغييرات والحلول التي يتم نشرها بسرعة وثقة. وبالإضافة إلى أفضل الممارسات الأخرى (مثل التغطية الكبيرة للاختبارات، والتنفيذ التلقائي/التعهدات البرمجية/التعهدات الموقعية وبيئات التدريج، وما إلى ذلك) تضمن مراجعات التعليمات البرمجية أيضاً أن ما يتم نشره آمن وسليم ويفي بالمتطلبات كما هو محدد.

الغرض من هذه الإرشادات واستخدامها

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

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

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

المسؤوليات المتعلقة بمراجعة التعليمات البرمجية

يتحمل كل فرد في الفريق مسؤوليات معينة فيما يتعلق بمراجعة التعليمات البرمجية. وفيما يلي بعض ما يجب فعله وما لا يجب فعله فيما يتعلق بمراجعة التعليمات البرمجية حسب الدور في العملية.

قائد المشروع

• افعل تأكد من أن مستودعاتك مهيأة بشكل جيد (على سبيل المثال، لا يُسمح بالدمج إلى فرعك الذي يواجه الإنتاج دون مراجعة واحدة على الأقل للموافقة).
• افعل التأكد من أن فريقك يفهم هذه الممارسات ويطبقها، والعمل بنشاط على تعزيز فهم سبب قيامنا بالأشياء بطريقة معينة.
• افعل ابحث عن أي حالات تعادل، حيث لا يمكن حل الآراء المتعارضة: بصفتك القائد الفني لفريقك، تقع على عاتقك مسؤولية اختيار الحل الأكثر ملاءمة في مثل هذه الحالات والحفاظ على تقدم العمل.
• ومع ذلك, لا تفعل استخدام قيادة المشروع كأداة غير حادة لا تفعل "سحب الرتبة". افعل نرحب بمراجعة حلولك ونقدها بقدر ما تشجعهم على عمل أي شخص.
• ضع في اعتبارك إضافة تكامل GitHub إلى قناة Slack الخاصة بفريقك. قد يكون من المفيد وضع طلبات المراجعة على رادارات المراجعين بشكل أفضل، ولكن اعتمادًا على الحجم الإجمالي في قناتك قد يكون هذا مناسبًا لفريقك وقد لا يكون مناسبًا.

عضو الفريق

• شارك في مراجعات التعليمات البرمجية. من غير المقبول عدم مراجعة التعليمات البرمجية.
• تذكّر أن تقوم بمراجعاتك البرمجية: فزملاؤك في الفريق يعتمدون عليك في التقدم في عملهم!
• إذا كنت لا تستطيع مطلقاً إجراء مراجعة معينة افعل توصيلها بوضوح وصراحة.
• ومع ذلك, لا تفعل افترض أنك لا تستطيع القيام بمراجعة معينة لأنك لا تعرف تلك الوحدة/الجانب من مواصفات النظام/منطق العمل. تعد مراجعة التعليمات البرمجية فرصة تعليمية مهمة.
• إذا كنت تشعر بأنك لا تعرف ما يكفي عن شيء ما لتقوم بمراجعة, افعل اسأل المؤلف عن ذلك: سيكون من دواعي سروره أن يشرح لك ما يفترض أن تفعله التغييرات.
• لا تفعل رفض المراجعات بناءً على مستوى الخبرة (لك أو المؤلف).
• افعل حاول مراجعة ما لا يقل عن عدد العلاقات العامة التي تقوم بإنتاجها. من الناحية المثالية، حافظ على أن تكون نسبة المراجعة المعطاة إلى المراجعة المطلوبة أعلى من 1 (خاصة في الفرق الكبيرة).

المؤلف

• افعل افهم أنه تقع على عاتقك مسؤولية مراجعة التعليمات البرمجية الخاصة بك - قد يبحث فريقك بشكل استباقي عن طلبات السحب لمراجعتها، لكن ليس من الضروري أن يفعلوا ذلك.
• لا تفعل قم دائمًا بتعيين/طلب المراجعات من نفس أعضاء الفريق - ستستفيد أكثر من مجموعة متنوعة من المراجعين (وعلى العكس، سيستفيد مجموعة أكبر من المطورين من مراجعة التعليمات البرمجية الخاصة بك)
• لا تفعل استبعاد شخص ما من المراجعة بناءً على الخبرة. يستفيد المطورون المبتدئون من مراجعة التعليمات البرمجية. يستفيد كبار المطورين من مراجعة التعليمات البرمجية. كما ورد في مقدمة هذه الوثيقة, الجميع الاستفادة من مراجعة الكود.
• ضع في اعتبارك باستخدام أداة عشوائية لاختيار المراجعين. على سبيل المثال في روبي %w[teammate1 teammate2 teammate3].Sample يمكن أن تصنع العجائب.
• افعل قم بتعيين اثنين على الأقل من المراجعين لطلبات السحب الخاصة بك، ما لم يكن ذلك مستحيلًا تمامًا. وبهذه الطريقة يستفيد عدد أكبر من الأشخاص من العملية (ومع وجود ثلاثة أشخاص يصعب الوصول إلى التعادل).
• افعل كن متجاوبًا في طلبات السحب الخاصة بك. على الرغم من أنه لا ينبغي أن تكسر تدفقك للرد في هذه اللحظة على أي تعليقات، تأكد من أن ردودك في الوقت المناسب - وإلا ستظل طلبات السحب الخاصة بك في مراجعة التعليمات البرمجية إلى أجل غير مسمى.
• افعل اتخاذ موقف منفتح. افترض دائماً أن مراجعك يحاول تقديم المساعدة بكل حسن نية. اشرح منطقك، وتناول حجج المراجع الخاص بك وأجب عن أسئلته.
• افعل كن مهذبًا. يحدث سوء التفاهم، ولكن لا يجب أن يخرج سوء التفاهم عن السيطرة ويضر بالأجواء في الفريق.
• افعل كن صادقًا. إذا كنت تعتقد أن هذا هو الحل الأفضل، فقل ذلك وقدم حججك. إذا أصبحت مقتنعاً بأن اقتراحات مراجعك أفضل مما أنتجته أنت، أخبرهم بذلك. إذا كنت تعتقد أنه يمكن إنتاج حل "أفضل ما في الأمرين" باستخدام أفكارك وأفكار مراجعك على حد سواء، فاقترحه عليهم. في النهاية، اعمل على التوصل إلى توافق في طلبات السحب الخاصة بك.
• افعل اترك حلّ تعليقاتهم لمراجعك - لا تحلّها فقط لأنك مقتنع بأن الأمر على ما يرام الآن.
• افعل اشرح بنشاط مهمتك ومنطقك ومتطلباتك الأخرى للمراجعين. لا بأس من عدم المعرفة - فمن غير المقبول حجب المعرفة.
• لا تفعل افترض أنك تعرف كل شيء - فنحن جميعًا متخصصون رائعون، ولكن من المهم أن تتحلى بقدر معين من التواضع في العمل معك.
• افعل كن المراجع الأول لرمزك. ارتدِ قبعة المراجع وافحص الكود بعناية كما تفعل مع الشخص الذي لا يعجبك في الغالب. حدد الأشياء الأكثر وضوحًا وتخلص منها، مثل الأسطر الفارغة أو أي بقايا أو مواصفات مفقودة. لا تتخطى أي شيء - ستتم الإشارة إليه على الأرجح على أي حال. لا تضيع وقت المراجعين!
• افعل وصف طلب السحب الخاص بك بدقة. يكون الوصف جيدًا عندما لا يفاجأ المراجع بأي شيء أثناء قراءة الشيفرة البرمجية. تذكر أنه لا يستطيع قراءة أفكارك. لهذا السبب من المهم وصف الأشياء غير الواضحة أو القرارات الرئيسية مع السبب أو جميع الأصناف والملفات الجديدة.
• ضع في اعتبارك باستخدام قالب طلب السحب. إذا كنت تستخدم Github، فأضفه إلى مستودعك ضمن .github/pull_request_template.md. يشجع جميع أعضاء الفريق على وصف طلبات السحب الخاصة بهم. كما أنه أسهل بكثير في الكتابة عندما يكون لديك حقل وصف مملوء بقالب. يمكنك هنا العثور على قالب نستخدمه في أحد مشاريعنا https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

المؤلف

• افعل أن تفهم أنه من مسؤوليتك أن يكون لديك مراجعة الكود - قد يبحث فريقك بشكل استباقي عن طلبات السحب لمراجعتها، ولكن ليس من الضروري أن يفعلوا ذلك.
• لا تفعل قم دائمًا بتعيين/طلب المراجعات من نفس مراجعو الأكواد - ستستفيد أكثر من مجموعة متنوعة من المراجعين (وعلى العكس، سيستفيد مجموعة أكبر من المطورين من مراجعة الكود الخاص بك)
• لا تفعل استبعاد شخص ما من المراجعة بناءً على الخبرة. يستفيد المطورون المبتدئون من أداء مراجعات الرموز. يستفيد كبار المطورين من أداء مراجعات الرموز. كما جاء في مقدمة هذه الوثيقة, الجميع فوائد من أداء مراجعات الرموز.

المراجع

• افعل استخدام لغة الاقتراح بدلاً من الاشتراط. بدلاً من قول "يجب عليك تحسين جودة التعليمات البرمجية بالقيام ب X بدلاً من X"قل "هل فكرت في تحسين جودة الكود عن طريق القيام ب X؟"
• افعل شرح اقتراحاتك "أعتقد أن X أفضل هنا لأنها تساعد في نقل المعرفة و تحسين جودة التعليمات البرمجية."
• حتى لو جاء اقتراحك من مصادر موضوعية (على سبيل المثال نمط الرمز إرشادات), افعل اطلب من المؤلف أن يفعل شيئًا ما بدلاً من أن تطلب منه أن يفعل شيئًا ما. "يُرجى الاحتفاظ بجميع الأدوات مجمدة وفقًا لـ نمط الرمز الدليل - [الرابط]"
• لا تفعل افترض أنك تعرف كل شيء. "على حد علمي أن هذه الأداة لا يجب أن تتجمد أبدًا، وفي ظل هذه الظروف ستفعل ذلك - هل هذا استثناء يحتاج إلى مراجعة الكود?"
• افعل استخدام لغة شاملة. "أعتقد أننا سنكون أفضل حالاً في المستقبل إذا قمنا ببناء هذا الأمر على هذا النحو. ما رأيك في هذا مراجعة أفضل للرموز اقتراح؟" و "ربما يجب أن نستخدم X هنا بدلًا من المراجعة الفعالة للشفرة البرمجية?"
• افعل كن سريعًا في القيام بـ مراجعات الرموز. لا يجب أن تكسر تدفقك للقيام بها، ولكن حاول أن تحافظ على الحلقة ضيقة إذا كان ذلك ممكنًا. يحب بعض الأشخاص القيام بها إما في بداية أو نهاية يوم عملهم، إما كـ"إحماء" أو "تهدئة".

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