تحية! أرغب اليوم في مشاركة النصائح حول كتابة رمز
مثالي مفهومة ، مأخوذ من كتاب بيتر جودليف ، "The Craft of a Programmer // The Practice of Writing Good Code".
بالطبع ، سيكون من الجيد قراءة هذا الكتاب المسلح لكل من يكتب الكود ، ولكن بالنسبة لأولئك الذين هم كسولون بشكل خاص ، ولكن الذين يريدون التوقف عن تعذيبهم بشكل أقل وتضليل زملائهم (
لديهم ضمير ) ، أقدم
10 مبادئ للتوثيق الذاتي تحت القط.
1. كتابة رمز بسيط مع التنسيق الجيد
تنسيق العرض التقديمي له تأثير كبير على سهولة فهم التعليمات البرمجية. ينقل التمثيل المعقول بنية الكود: تصبح الدوال والحلقات والعبارات الشرطية أكثر وضوحًا.
int fibonacci(int position) { if (position < 2) { return 1; } int previousButOne = 1; int previous = 1; int answer = 2; for (int n = 2; n < position; ++n) { previousButOne = previous; previous = answer; answer = previous + previousButOne; } return answer; }
2. اختيار أسماء ذات معنى
يجب أن تكون أسماء جميع المتغيرات والأنواع والملفات والوظائف ذات معنى وليس مضللة. يجب أن يصف الاسم بشكل صحيح ما هو عليه. إذا لم تتمكن من العثور على اسم ذي معنى ، فهناك شك فيما إذا كنت تفهم طريقة تشغيل الشفرة أم لا.
يجب أن يكون نظام التسمية ثابتًا ولا يسبب مفاجآت غير سارة. تأكد من أن المتغير يستخدم دائمًا فقط للغرض الذي يشير إليه اسمه.
اختيارًا جيدًا للأسماء هو أفضل طريقة لتجنب التعليقات غير الضرورية. الأسماء هي أفضل طريقة لتقريب الكود من تعبير اللغات الطبيعية.
3. تقسيم التعليمات البرمجية إلى وظائف مستقلة
كيف تقوم بتقسيم الشفرة إلى وظائف وما هي الأسماء التي تمنحها يمكن أن تجعل الشفرة مفهومة أو غير مفهومة تمامًا.
تقليل أي آثار
جانبية غير متوقعة ، بغض النظر عن مدى قد تبدو مفيدة. سوف تتطلب وثائق إضافية.
اكتب وظائف قصيرة. فهي أسهل للفهم. يمكنك التنقل في خوارزمية معقدة إذا كانت مقسمة إلى أجزاء صغيرة بأسماء ذات معنى ، ولكن لا يمكن القيام بذلك في كتلة الشفرة غير المجسمة.
4. اختر أسماء أنواع ذات معنى
قم بوصف القيود أو السلوك إلى أقصى حد ممكن باستخدام ميزات اللغة المتاحة. على سبيل المثال:
- عند تحديد قيمة لن تتغير ، قم بتعيين نوع ثابت لها (استخدم const في C).
- إذا كان يجب ألا يأخذ المتغير قيمًا سلبية ، فاستخدم نوعًا غير موقع (إذا كان موجودًا في اللغة).
- استخدم التعدادات لوصف مجموعة البيانات المرتبطة.
- اختر نوع المتغيرات بشكل صحيح. في C / C ++ ، اكتب حجمًا لمتغيرات type size_t ، ونتائج العمليات الحسابية مع مؤشرات إلى متغيرات type ptrdiff_t .
5. استخدام الثوابت المسماة
رمز مثل
إذا (عداد == 76) أمر محير. ما هو المعنى السحري لل 76؟ ما هو معنى هذا الاختيار؟ ممارسة الأعداد السحرية شريرة. أنها تحجب معنى الكود. من الأفضل أن تكتب مثل هذا:
const size_t bananas_per_cake = 76; ... if (count == bananas_per_cake) { // }
إذا تم العثور على الكود 76 الثابت دائمًا في الكود (عفواً ،
bananas_per_cake ) ، تتحقق ميزة إضافية: عندما يكون من الضروري تغيير محتوى الموز في الفطيرة ، يكفي تعديل الكود في مكان واحد ، بدلاً من إجراء بحث / تغيير عالمي للرقم 76 ، وهو أمر محفوف بالأخطاء.
هذا لا ينطبق فقط على الأرقام ، ولكن أيضًا على السلاسل الثابتة. ألقِ نظرة على
أي حرفية في الشفرة ، خاصةً إذا كانت تحدث بشكل متكرر. ألن يكون من الأفضل استخدام الثوابت المسماة بدلاً من ذلك؟
6. تسليط الضوء على القطع الهامة من التعليمات البرمجية
محاولة لتسليط الضوء على رمز مهم على خلفية المواد العادية. في المكان المناسب ، يجب أن تحصل على انتباه القارئ. هناك عدد من الحيل لهذا الغرض. على سبيل المثال:
- ضع الإعلانات في الفصل الدراسي بحكمة. أولاً ، يجب أن تذهب المعلومات المتعلقة بالكائنات المفتوحة ، لأن المستخدم للفئة هو الذي يحتاجها. يجب وضع تفاصيل التنفيذ المغلقة في النهاية ، لأنها أقل إثارة للاهتمام بالنسبة لمعظم القراء.
- إذا أمكن ، قم بإخفاء جميع المعلومات غير الأساسية. لا تترك القمامة غير الضرورية في مساحة الاسم العالمية. C ++ لديه المصطلح pimpl ، والذي يسمح لك بإخفاء تفاصيل تنفيذ الفصل. (مايرز 97).
- لا تخفي رمز مهم. لا تكتب أكثر من عبارة واحدة في سطر واجعل هذه العبارة بسيطة. تتيح لك اللغة إمكانية كتابة عوامل تشغيل مبتكرة للغاية من أجل for for ، حيث يكون كل المنطق مناسبًا في سطر واحد بمساعدة العديد من الفواصل ، لكن يصعب قراءته. تجنبهم.
- الحد من عمق تداخل البيانات الشرطية. خلاف ذلك ، من الصعب ملاحظة معالجة الحالات المهمة حقًا وراء كومة من ifs و الأقواس.
7. الجمع بين البيانات ذات الصلة
يجب أن تكون جميع المعلومات ذات الصلة في مكان واحد. خلاف ذلك ، سوف تجعل القارئ ليس فقط القفز من خلال الأطواق ، ولكن أيضا البحث عن هذه الأطواق مع ESP. يجب تمثيل واجهة برمجة التطبيقات لكل مكون بملف واحد. إذا كان هناك الكثير من المعلومات المترابطة التي يجب تقديمها في مكان واحد ، فإن الأمر يستحق مراجعة بنية الرمز.
إذا أمكن ، ادمج الكائنات باستخدام تصميمات اللغة. في C ++ و C # ، يمكنك دمج عناصر داخل نفس
مساحة الاسم . في Java ، يعد محرك الحزمة أداة اتحاد. يمكن تعريف الثوابت ذات الصلة في التعداد.
8. تسمية الملفات
ضع كتلة تعليق في بداية الملف مع وصف لمحتويات الملف والمشروع الذي يتعلق به. هذا لا يتطلب الكثير من العمل ، لكنه ذو فائدة كبيرة. أي شخص لديه لمرافقة هذا الملف سوف تحصل على فكرة جيدة عن ما هو التعامل معها. قد يكون لهذا العنوان معنى خاص: تتطلب معظم شركات البرمجيات ، لأسباب قانونية ، أن يكون لكل ملف مصدر بيان حقوق نشر. عادةً ما تبدو رؤوس الملفات على النحو التالي:
/********************************************************* * File: Foo.java * Purpose: Foo class implementation * Notice: (c) 1066 Foo industries. All rights reserved. ********************************************************/
9. التعامل مع الأخطاء بشكل صحيح
ضع معالجة جميع الأخطاء في السياق الأنسب. إذا كانت هناك مشكلة في القراءة / الكتابة على القرص ، فيجب معالجتها في التعليمات البرمجية التي تتناول الوصول إلى القرص. لمعالجة هذا الخطأ ، قد تحتاج إلى إنشاء خطأ آخر (مثل استثناء "لا يمكنني تحميل الملف") ، ونقله إلى مستوى أعلى. هذا يعني أنه في كل مستوى من مستويات البرنامج ، يجب أن يكون الخطأ وصفًا دقيقًا للمشكلة في
سياقها . لا معنى للتعامل مع الخطأ المرتبط بفشل القرص في رمز واجهة المستخدم.
يساعد رمز التوثيق الذاتي القارئ على فهم مكان حدوث الخطأ وما يعنيه وما هي عواقبه بالنسبة للبرنامج في الوقت الحالي.
10. اكتب تعليقات مفيدة
لذلك ، حاولنا تجنب كتابة التعليقات باستخدام طرق أخرى غير مباشرة لتوثيق الكود. ولكن بعد بذل كل جهد ممكن لكتابة تعليمات برمجية مفهومة ، يجب تزويد كل شيء آخر بالتعليقات. لتسهيل فهم الكود ، يجب استكماله مع قدر
مناسب من التعليقات. أي واحد؟
جرب الحيل الأخرى أولاً. على سبيل المثال ، تحقق مما إذا كان يمكنك جعل الشفرة أكثر وضوحًا عن طريق تغيير الاسم أو عن طريق إنشاء وظيفة مساعد ، وبالتالي تجنب التعليق.
أنا متأكد من أنه بعد إدخال العديد من هذه المبادئ في العادة ، ستجعل مبرمجًا واحدًا أكثر سعادة. وسوف تكون هذا مبرمج سعيد. متى؟ في وقت العودة إلى العمل على رمزه قبل ستة أشهر.