وثيقة المعايير

Question

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

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

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

• كيف تصطف بين قوسين؟هل تتبع نفس إرشادات الأقواس عند التعامل مع الفئات، والأساليب، ومحاولة التقاط الكتل، وبيانات التبديل، وكتل if else، وما إلى ذلك؟

• هل تصطف الحقول في عمود؟هل تقوم بتدوين/بادئة المتغيرات الخاصة بشرطة سفلية؟هل تتبع أي اصطلاحات تسمية لتسهيل العثور على التفاصيل في الملف؟كيف تقوم بترتيب أعضاء صفك؟

ماذا عن الاقتراحات الخاصة بمساحات الأسماء أو التغليف أو معايير مجلد/مؤسسة التعليمات البرمجية المصدر؟أميل إلى البدء بشيء مثل:

<com|org|...>.<company>.<app>.<layer>.<function>.ClassName

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

Answer 1

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

إذا كنت تستخدم لغة بمعيار موجود (على سبيل المثال،Java، C#)، فمن الأسهل استخدامها، أو على الأقل البدء بها كمسودة أولى.لقد فكرت صن كثيرًا في قواعد التنسيق الخاصة بها؛قد تستفيد منه أيضًا.

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

Answer 2

قادمة من صناعة السيارات، إليك بعض معايير الأسلوب المستخدمة لأسباب محددة:

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

if(...)
{

}

تحتوي جميع المفاتيح/التحديدات على حالة افتراضية.تسجل الحالة الافتراضية خطأ إذا لم يكن المسار صالحًا.

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

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

while(stillwaiting())
{
   ;
}

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

وهناك آخرون، ولكن هذه هي قمة رأسي.

-آدم

Answer 3

سأؤيد اقتراح جيسون.

لقد أكملت للتو وثيقة معايير لفريق مكون من 10 إلى 12 شخصًا يعملون في الغالب بلغة Perl.تقول المستند لاستخدام "المسافة البادئة التي تشبه بيرلتيدي لهياكل البيانات المعقدة." لقد زودنا الجميع أيضًا بإعدادات Perltidy مثال على تنظيف التعليمات البرمجية الخاصة بهم لتلبية هذا المعيار.لقد كان واضحًا للغاية ومتوافقًا مع معايير الصناعة بالنسبة للغة، لذلك حصلنا على صفقة شراء رائعة من قبل الفريق.

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

نأمل أن ينجح الأمر!

Answer 4

ومن الواضح أن الأمر يختلف باختلاف اللغات والتقنيات.من خلال النظر إلى مساحة الاسم الخاصة بك، سأخمن جافا، في هذه الحالة http://java.sun.com/docs/codeconv/ هو مكان جيد حقا للبدء.قد ترغب أيضًا في إلقاء نظرة على شيء مثل بنية الدليل القياسية الخاصة بـ maven والتي ستجعل جميع مشاريعك تبدو متشابهة.