Python Doctests / Sphinx: Guide Style ، كيفية استخدامها ولديها رمز قابل للقراءة؟

Question

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

ومع ذلك ، في كثير من الأحيان ، أنتهي من فعل أشياء مثل هذا:

"""
Descriptions
=============

bla bla bla ...

    >>> test
    1
bla bla bla + tests tests tests * 200 lines = poor readability of the actual code
"""

ما أعنيه هو أنني أضع جميع اختباراتي مع تفسيرات الوثائق في الجزء العلوي من الوحدة ، لذلك عليك التمرير بغباء للعثور على الكود الفعلي ، وهذا أمر قبيح للغاية (في رأيي). ومع ذلك ، أعتقد أنه يجب أن يبقى الدكتوراه في الوحدة ، لأنه يجب أن تكون قادرًا على قراءتها أثناء قراءة الكود المصدري. لذا ، يأتي سؤالي: عشاق sphinx/doctests ، كيف تنظم الدكتوراه ، مثل قابلية قراءة الكود لا تعاني؟ هل يوجد دليل على الأزياء للأثرياء ، لأبو الهول؟ للدستور مع أبو الهول ، هل تستخدم دليل نمط Google أو Sphinx أو أي شيء آخر ؟

Answer 1

أعتقد أن هناك نوعان من الدكتوراه.

1. يمكنك وضع شيء ما في docstring للوظيفة ، ولكن إذا كان الأمر كذلك ، فابقيه قصيرًا وبسيطًا.
2. الخيار الآخر هو الوثائق/البرنامج التعليمي الكامل ، وأنا أفعل ذلك كملف منفصل.

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