تتضمن التعليمات البرمجية الجيدة تعليقات للمساعدة في فهمها ، ويمكن أن تلعب سلاسل المستندات دورًا رئيسيًا في ذلك.

بدون التوثيق المناسب ، قد يكون من الصعب فهم التعليمات البرمجية الخاصة بك وصيانتها وتصحيحها. في Python ، يمكنك استخدام سلاسل docstrings لتقديم أوصاف موجزة وأمثلة عن كيفية عمل الكود.

ما هي Docstrings؟

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

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

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

كيف تكتب دوكسترينغ

عادةً ما تقوم بتضمين سلاسل مستندات في بداية كتلة التعليمات البرمجية التي تريد توثيقها. يجب عليك إرفاقها في ثلاث علامات اقتباس (). يمكنك كتابة سلاسل من سطر واحد أو سلاسل مستندات متعددة الأسطر.

instagram viewer

تعد سلاسل المستندات المكونة من سطر واحد مناسبة للرمز البسيط الذي لا يتطلب الكثير من التوثيق.

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

defتتضاعف(أ ، ب):
يضاعف عددين ويعيد النتيجة
يعود أ * ب

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

ضع في اعتبارك فئة السيارة التالية:

فصلسيارة:

 أ فصليمثلأسيارةهدف.
 صفات:
 الأميال (العائمة): الأميال الحالية للسيارة.


 طُرق:
 القيادة (بالأميال): يقود السيارة ل العدد المحدد من الأميال.


def__فيه__(النفس ، الأميال):
 الأميال الذاتية = الأميال


defيقود(نفس ، أميال):

 يقود السيارة ل العدد المحدد من الأميال.


 أرغس:
 أميال (تطفو): عدد الأميال التي يجب القيادة.
 عائدات:
لا أحد

 الأميال الذاتية + = الأميال

يصف docstring للفئة أعلاه ما يمثله الفصل وصفاته وطرقه. وفي الوقت نفسه ، توفر المستندات الخاصة بالطريقة drive معلومات حول ما تفعله هذه الطريقة ، والحجج التي تتوقعها ، والعناصر التي تُرجعها.

هذا يسهل على أي شخص يعمل مع هذا الفصل فهم كيفية استخدامه. تشمل الفوائد الأخرى لاستخدام docstrings ما يلي:

  • قابلية صيانة الكود: من خلال توفير وصف واضح لكيفية عمل الكود ، تساعد سلاسل المستندات المطورين على تعديل الكود وتحديثه دون حدوث أخطاء.
  • تعاون أسهل: عندما يتعاون العديد من المطورين على نفس قاعدة التعليمات البرمجية — على سبيل المثال ، مع أداة Visual Studio Live Share—تسمح السلاسل للمطورين بتوثيق الشفرة باستمرار حتى يتمكن كل فرد في الفريق من فهمها.
  • تحسين قراءة الكود: توفر Docstrings ملخصًا عالي المستوى لما يسمح به الرمز أي شخص يقرأ الكود لفهم الغرض منه بسرعة دون المرور بالشفرة بالكامل حاجز.

تنسيقات Docstring

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

يحتوي تنسيق docstring الأساسي على الأقسام التالية:

  • سطر التلخيص: ملخص من سطر واحد لما يفعله الكود.
  • الوسيطات: معلومات حول الوسيطات التي تتوقعها الدالة بما في ذلك أنواع البيانات الخاصة بها.
  • قيمة الإرجاع: معلومات حول قيمة إرجاع الدالة بما في ذلك نوع بياناتها.
  • الزيادات (اختياري): معلومات حول أي استثناءات قد تثيرها الوظيفة.

هذا مجرد تنسيق أساسي حيث توجد تنسيقات أخرى يمكنك اختيارها لبناء سلاسل مستنداتك. وأكثرها شيوعًا هي Epytext و reStructuredText (المعروف أيضًا باسم reST) و NumPy و Google docstrings. كل من هذه التنسيقات لها بناء الجملة الخاص بها كما هو موضح في الأمثلة التالية:

Epytext

سلسلة وثيقة تتبع تنسيق Epytext:

defتتضاعف(أ ، ب):

 اضرب عددين معًا.
 param a: الرقم الأول المراد ضربه.
 @ type a: int
 param b: الرقم الثاني المراد ضربه.
 @ النوع ب: int
 return: حاصل ضرب الرقمين.
 @ النوع: int

يعود أ * ب

reStructuredText (reST)

سلسلة وثيقة تتبع تنسيق reST:

defتتضاعف(أ ، ب):

 اضرب عددين معًا.
: param a: الرقم الأول المراد ضربه.
: اكتب a: int
: param b: الرقم الثاني المراد ضربه.
: اكتب ب: int
 :يعود: حاصل ضرب العددين.
: rtype: int

يعود أ * ب

NumPy

سلسلة وثيقة تتبع تنسيق NumPy:

defتتضاعف(أ ، ب):

 اضرب عددين معًا.
 حدود

 أ: int
 الرقم الأول المراد ضربه.
 ب: int
 الرقم الثاني المطلوب ضربه.
 عائدات

 int
 حاصل ضرب العددين.

يعود أ * ب

جوجل

سلسلة مستندات تتبع تنسيق Google:

defتتضاعف(أ ، ب):

 اضرب عددين معًا.
 أرغس:
 a (int): الرقم الأول المراد ضربه.
 b (int): الرقم الثاني الذي يجب ضربه.
 عائدات:
 int: حاصل ضرب الرقمين.

يعود أ * ب

على الرغم من أن جميع تنسيقات docstring الأربعة توفر وثائق مفيدة لوظيفة المضاعفة ، إلا أن تنسيقات NumPy و Google أسهل في القراءة من تنسيقات Epytext و reST.

كيفية تضمين الاختبارات في السلاسل

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

لاستخدام المبادئ ، قم بتضمين مدخلات العينة والمخرجات المتوقعة في سلسلة الوثائق. فيما يلي مثال على كيفية القيام بذلك:

defتتضاعف(أ ، ب):

 اضرب عددين معًا.
 حدود

 أ: int
 الرقم الأول المراد ضربه.
 ب: int
 الرقم الثاني المطلوب ضربه.


 عائدات

 int
 حاصل ضرب العددين.
 أمثلة

 >>> ضرب (2, 3)
6
 >>> ضرب (0, 10)
0
 >>> ضرب (-1, 5)
-5

يعود أ * ب

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

python -m تعليمات الضرب

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

كيفية إنشاء وثائق من Docstrings

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

يعد Sphinx أحد أشهر مولدات التوثيق التي يمكنك استخدامها. وهو يدعم تنسيق reST docstring افتراضيًا ولكن يمكنك تهيئته للعمل مع تنسيق Google أو NumPy.