لا أعرف ما إذا كان أصدقائي مرتبكين للغاية. عندما ننظر إلى الوراء في بعض التعليمات البرمجية التي كتبناها قبل 6 أشهر ، غالبًا ما نشعر بالارتباك.
هناك العديد من الطرق في Python لمساعدتنا على فهم الأعمال الداخلية لشفرتنا ، ويمكن لعادات البرمجة الجيدة أن تجعل عملنا أكثر كفاءة!
على سبيل المثال ، قد ينتهي بنا الأمر برمز يشبه إلى حد كبير الصورة أدناه. ليس الأسوأ ، لكننا بحاجة إلى توسيع بعض الأشياء مثل:
-
ماذا تعني f و d في دالة load_las_file؟ -
لماذا نتحقق من النتيجة في وظيفة الطين؟ -
ما هي الأنواع التي تحتاجها هذه الوظائف؟ يطفو؟
في هذه المقالة ، سنركز على خمس نصائح أساسية حول كيفية تحسين قابلية قراءة التطبيق / البرنامج النصي الخاص بك من خلال التوثيق ، والمطالبة بالإدخال ، وأسماء المتغيرات المناسبة.
1. التعليقات
أول شيء يمكننا القيام به مع الكود الخاص بنا هو إضافة تعليقات معينة إلى الكود الخاص بنا ، ولكن دون المبالغة في ذلك. يجب أن تخبرك التعليقات لماذا تعمل الشفرة أو لماذا يتم عمل شيء ما بطريقة معينة ، وليس كيف يعمل.
عادةً ما تتم التعليقات في Python باستخدام علامة الجنيه (#) ويمكن أن تمتد على سطر واحد أو عدة أسطر.
# Comment using the hashtag
# Another comment using the hashtag
للتعليقات متعددة الأسطر ، يمكننا أيضًا استخدام ثلاث علامات اقتباس مزدوجة.
"""
This is an example of
a multi-line comment
"""
في المثال أدناه ، تمت إضافة بعض التعليقات إلى الكود لشرح سير العمل والاستدلال وراء أسطر معينة من التعليمات البرمجية
2. كتابة صريحة
يتم كتابة لغة Python ديناميكيًا ، مما يعني أن الأنواع المتغيرة يتم فحصها فقط في وقت التشغيل. أيضًا ، يمكن للمتغيرات تغيير النوع أثناء تنفيذ التعليمات البرمجية.
من ناحية أخرى ، تتضمن الكتابة الثابتة تحديد نوع المتغير بشكل صريح ولا يمكن تغييره أثناء تنفيذ الكود.
في عام 2014 ، قدم PEP 484 مفهوم تلميحات الكتابة ، ولاحقًا في Python 3.5 ، تتيح لنا هذه التلميحات تحديد نوع المتغير بشكل صريح.
من خلال إضافة تلميحات الكتابة ، يمكنك تحسين قابلية قراءة التعليمات البرمجية بشكل ملحوظ. في المثال التالي ، يمكننا بسهولة الحصول على المعلومات التالية:
-
تتطلب الوظيفة معلمتين -
يجب أن تكون معلمة اسم الملف من نوع السلسلة -
يجب أن تكون المعلمة start_depth من النوع float ، والقيمة الافتراضية هي None -
ستعيد الوظيفة كائن DataFrame الباندا
يمكننا أن نقول على الفور بالضبط ما تحتاجه الوظيفة وما ستعود إليه بناءً على تلميحات الكتابة.
3. Docstrings (سلاسل التوثيق)
Docstrings هي سلسلة حرفية تتبع مباشرة تعريف دالة أو فئة ، Docstrings هي طريقة رائعة لشرح بالتفصيل ما تفعله وظيفتنا ، وما هي الحجج التي تأخذها ، وأي استثناءات تطرحها ، وما ترجع إليه ، وما إلى ذلك. انتظر.
أيضًا ، إذا استخدمنا أداة مثل Sphinx لإنشاء توثيق عبر الإنترنت للرمز ، فسيتم تلقائيًا التقاط سلاسل المستندات وتحويلها إلى التوثيق المناسب.
يوضح المثال التالي سلسلة docstring clay_volumeلوظيفة .
هنا يمكننا تحديد ماهية كل معلمة ، والتي تكون أكثر تفصيلاً من تلميحات الكتابة الأساسية ، ويمكننا أيضًا تضمين المزيد من المعلومات حول الطريقة الكامنة وراء الوظيفة ، مثل المراجع الأكاديمية أو المعادلات.
يعد وجود سلاسل مستندات مفيدًا جدًا أيضًا عندما نستدعي وظائف من مكان آخر في الكود. على سبيل المثال ، عند تحرير التعليمات البرمجية باستخدام Visual Studio ، يمكنك التمرير فوق مكالمة دالة ومعرفة ما تفعله الوظيفة والنوافذ المنبثقة التي تتطلبها.
إذا استخدمنا Visual Studio Code (VSCode) لتحرير كود Python الخاص بنا ، فيمكننا استخدام ملحقات مثل autoDocstring لتبسيط عملية إنشاء سلاسل المستندات. يسمح لنا المكون الإضافي بإدخال ثلاث علامات اقتباس مزدوجة وملء بقية القالب تلقائيًا ، نحتاج فقط إلى التركيز على التفاصيل الأخرى التي يجب ملؤها.
4. أسماء المتغيرات المقروءة
في كثير من الأحيان ، عندما نكتب رمزًا ، لا نهتم كثيرًا بأسماء المتغيرات ، خاصة عندما نكون في عجلة من أمرنا لإكمال بعض الوظائف. ولكن إذا كانت الكود الخاص بنا يعرض سلسلة من المتغيرات المسماة x1 أو var123 ، فمن المحتمل ألا يفهم أحد للوهلة الأولى ما تمثله.
في المثال أدناه ، لدينا متغيرين f و d. يمكن تخمين هذه المعاني من خلال النظر إلى أجزاء أخرى من الكود ، لكن الأمر سيستغرق بعض الوقت ، خاصة إذا كانت الشفرة طويلة جدًا.
إذا قمنا بتعيين أسماء مناسبة لهذه المتغيرات ، فإننا نعلم أن أحدها هو ملف data_file الذي يقرأه استدعاء lasio.read () ، وعلى الأرجح البيانات الأولية ، ويخبرنا متغير البيانات أن هذه هي البيانات الفعلية نحن أعمل مع.
5. تجنب الأرقام السحرية
الأرقام السحرية هي قيم في الكود لها الكثير من المعنى غير المبرر وراءها ويمكن أن تمثل الثوابت. يمكن أن يؤدي استخدام هذه في التعليمات البرمجية إلى الغموض ، خاصة بالنسبة لأولئك الذين ليسوا على دراية بأي حسابات تستخدم فيها الأرقام.
أيضًا ، إذا كان لدينا نفس الرقم السحري في أماكن متعددة واحتجنا إلى تحديثه ، فسيتعين علينا تحديث كل مثيل له. ومع ذلك ، تكون العملية برمتها أسهل بكثير إذا تم تعيين الأرقام لمتغيرات مسماة بشكل صحيح.
في المثال أدناه ، لدينا دالة تحسب قيمة تسمى النتيجة وتضربها في 0.6. من خلال الكود ، لا يمكننا معرفة المعنى المحدد للكود بدقة
إذا أعلنا عن متغير وقمنا بتعيين هذه القيمة إليه ، فستكون لدينا فرصة أفضل لمعرفة ماهيته. في هذه الحالة ، هي نسبة الصلصال إلى الصخر الزيتي المستخدمة لتحويل مؤشر أشعة جاما إلى حجم الطين.
لخص
إضافة الوثائق إلى الكود الخاص بنا عبر التعليقات والسلاسل يمكن أن تقطع شوطًا طويلاً لمساعدة أنفسنا والآخرين على فهم ما يفعله الكود. في الواقع ، قد يبدو الأمر وكأنه عمل روتيني في البداية ، ولكن مع استخدام الأدوات والممارسة المنتظمة ، يمكن أن تصبح طبيعة ثانية بالنسبة لك.
انقر هنا👇 لمتابعة لي ، وتذكر وضع علامة على النجمة ~
اقتراحات للقراءة
استشارة بالطبع CDA