نظرًا لأننا نعرف بالفعل كيفية كتابة التعليقات متعددة الأسطر ، فقد نستخدم علامات الاقتباس المفردة الثلاثية أو علامات الاقتباس المزدوجة الثلاثية. نستخدم سلسلة التوثيق عندما نريد وصف وظائفنا حتى نتمكن من الحصول على الوثائق عندما نحتاج إليها. تمنحك بعض IDEs الوثائق عن طريق تمرير الماوس فوق الاسم وبعضها يبرز كلمات رئيسية معينة. لكن الحقيقة هي أن docstrings في NumPy أكثر مرونة من اللغات الأخرى. Docstring هي سلسلة حرفية تحدث في بداية تعريف الوظيفة. علينا تقديم قيم محددة أثناء استخدام سلاسل المستندات في حالات الوظائف والفئات وما إلى ذلك.
عند استخدام docstrings مع الدوال ، يتعين علينا تمرير الحجج. عند استخدامها مع الفئات ، نمرر السمات والطرق. في حالة الوحدات النمطية ، يتعين علينا تقديم قائمة بالفئات والوظائف. في حالة الحزمة ، نقوم بتمرير قائمة الوحدات ذات الوظائف. إذن ، الغرض الأساسي من سلسلة docstring ، كما يشرح الاسم ، أنها تساعد في توثيق الكود الخاص بنا. نحن نقوم بالتوثيق حتى إذا استخدم شخص ما الكود الخاص بنا في المستقبل ، فسيكون قادرًا على فهم الكود الخاص بنا والمنطق وراء الكود الخاص بنا بمساعدة docstring. تحتوي الوظائف المضمنة أيضًا على سلاسل مستندات فيها ؛ يمكننا استخدام وظيفة help () للنظر في docstring للوظائف المضمنة.
هناك بعض الاختلافات بين التعليقات والسلاسل. يتم تجاهل التعليقات من قبل المترجمين الفوريين ولكن لا يتم تجاهل النصوص من قبل المترجمين الفوريين. الذاكرة مخصصة للوثائق. التعليق هو وصف للكود ولكن من ناحية أخرى ، تخبرنا سلاسل الوثائق الغرض من الكود.
بناء الجملة:
صيغة كتابة السلاسل في NumPy هي:
'' 'رسالة Docstring' ''
أو
'' 'رسالة Docstring' '
يرجى ملاحظة أن docstring ليس وظيفة أو طريقة ، لذلك ليس لديها بناء الجملة الصحيح. الشيء الوحيد الذي يجب ملاحظته هنا هو أننا نبدأ سلسلة التوثيق بثلاثة اقتباسات مفردة أو ثلاث علامات اقتباس مزدوجة. نكتب وصفنا للرمز وننهيها مرة أخرى بثلاثة اقتباسات مفردة أو ثلاث علامات اقتباس مزدوجة في النهاية. لا يوجد شيء إلزامي للكتابة لسلاسل الوثائق. عليك فقط وضع ثلاث علامات اقتباس مفردة أو مزدوجة قبل وصف السلسلة الخاصة بك وبعدها.
مثال 1:
لفهم السلاسل بطريقة أفضل ، دعنا نقدم مثالاً. في هذا المثال ، بعد تضمين مكتبة NumPy ، نعلن ببساطة عن المتغير 'a' ومتغير آخر 'b'. بعد ذلك ، نقوم بإنشاء سلسلة docstring الخاصة بنا والتي تقول 'دعونا نضيف متغيرين' أ 'و' ب '. في حالتنا ، هذا مثال سهل ولكن إذا كان كودنا معقدًا ، فهذا يساعد المبرمج كثيرًا في فهم الكود. بعد ذلك ، نلخص المتغيرين 'أ' و 'ب' ونخزن ناتجهما في متغير آخر وهو 'ج'. أخيرًا ، نطبع قيمة المتغير 'c'. الآن ، نقوم بتنفيذ التعليمات البرمجية الخاصة بنا.
يستورد حبيبي كما على سبيل المثالأ = 1
ب = اثنين
'' 'لنضيف متغيري a و b' '
ج = أ + ب
مطبعة ( ج )
هذا هو ناتجنا من جزء معين من الكود. يمكننا أن نرى أن النظام لم يقدم أي خطأ بشأن بناء الجملة غير الصحيح أو أي شيء للسطر 7 من الكود الخاص بنا. أيضًا ، لم يقم النظام بطباعة docstring الخاص بنا. بدلاً من ذلك ، قام فقط بطباعة مخرجات المتغير 'c' الذي أخبرنا نظامنا بالطباعة. يوضح هذا كيف تعمل السلاسل. في المرة القادمة ، عندما يحاول المبرمج الجديد العمل على الكود الخاص بنا ، سوف يفهم ما الذي نفعله بمساعدة docstring الخاص بنا. لكن لن تتم طباعته كإخراج حتى لا يزعج مستخدم الكود.
المثال 2:
الآن ، نقدم مثالًا معقدًا لفهم عمل سلسلة docstring. أولاً ، نقوم بتضمين مكتبة NumPy ثم نكتب سلسلة doc التي نشرح فيها السطر التالي من التعليمات البرمجية حيث نشرح تهيئة المصفوفة. نضيف أيضًا سلاسل المستندات في الجزء الآخر من الكود. الآن ، إذا شاركنا هذا الرمز مع أي مطور Python جديد دون إضافة سلاسل المستندات ، فسيكون من الصعب عليه بطريقة ما معرفة عمل هذا الرمز والغرض منه. عليه أن يبحث أولاً عن الوظائف التي استخدمناها. ولكن إذا أضفنا سلسلة docstring إلى الكود الخاص بنا ، فسيكون من السهل على المطورين الآخرين فهم الكود دون دراسة المزيد حول الوظائف. لسنا مقيدون بإضافة التعليقات لبعض الحدود ؛ يمكن أن تتكون التعليقات من سطر واحد أو أكثر. يمكن أيضًا إضافته أكثر من مرة في رمز. ثم قم باستيراد NumPy كـ np.
'' إنشاء المتغير الذي سنمرر إليه مصفوفة بحجم 1 × 6 ''مجموعة مصفوفة = على سبيل المثال مجموعة مصفوفة ( [ أحد عشر و 22 و 33 و 44 و 55 و 66 ] )
'' تعيين المصفوفة لوظيفة tofile () للسماح بحفظها في الملف المسمى arr ''
مجموعة مصفوفة . إلى ملف ( 'arr.bin' )
'' عرض الملف باستخدام وظيفة fromfile ''
مطبعة ( على سبيل المثال من - الملف ( 'arr.bin' و dtype = int ) )
كما هو موضح في المقتطف التالي ، لا يتم عرض سلاسل المستندات في الإخراج مما يعني أنها لا تؤثر على إخراج أو تجميع الشفرة. يتم تجاهل Docstrings أثناء عملية التجميع.
استنتاج
في هذا الدليل ، تعلمنا عن docstrings في NumPy. قمنا بمقارنة النصوص بالتعليقات وشرحنا الفرق بينهما. لقد تعلمنا بناء جملة docstrings وكيفية كتابة السلاسل في الكود الخاص بنا. علاوة على ذلك ، حاولنا أيضًا شرح ما هي السلاسل في NumPy وكيف تعمل بمساعدة الأمثلة. أخيرًا ، لاحظنا أنها ضرورية للمبرمجين. لن نكرر أهمية سلاسل المستندات في NumPy. سنقول فقط أنه يجب عليك استخدام سلاسل المستندات في التعليمات البرمجية الخاصة بك. في NumPy ، يعد أسلوب كتابة السلاسل هو الأكثر شيوعًا. يتم استخدامه على نطاق واسع في مجتمع البرمجة للسماح لبعضهم البعض بمعرفة عمل ووظائف أكوادهم. سيساعدك هذا الدليل على البدء في استخدام مستندات NumPy. حاولنا تغطية معظم ما ستحتاج إليه باستخدام سلاسل المستندات في NumPy.