كيفية كتابة مستندات ذات معنى؟

Question

ما هو، في رأيك، مستند ذو معنى؟ماذا تتوقع أن يتم وصفه هناك؟

على سبيل المثال، فكر في فئة بايثون هذه __init__:

def __init__(self, name, value, displayName=None, matchingRule="strict"):
    """
    name - field name
    value - field value
    displayName - nice display name, if empty will be set to field name
    matchingRule - I have no idea what this does, set to strict by default
    """

هل تجد هذا ذا معنى؟انشر أمثلةك الجيدة/السيئة ليعرفها الجميع (وإجابة عامة حتى يمكن قبولها).

Answer 1

وأنا أتفق مع "أي شيء لا تستطيع ان تقول من توقيع طريقة ل". أنه قد يعني أيضا أن أشرح ما طريقة / ترجع الدالة.

وأنت قد ترغب أيضا في استخدام أبو الهول (ووتركيب reStructuredText) لأغراض التوثيق داخل جمل التوثيق الخاص بك. وبهذه الطريقة يمكنك تضمين هذا في الوثائق بسهولة. للحصول على مثال تحقق من مثل repoze.bfg الذي يستخدم على نطاق واسع هذا (<لأ href = "HTTP: // إس. repoze.org/repoze.bfg/trunk/repoze/bfg/location.py "يختلط =" noreferrer "> مثال ملف و <لأ href =" http://svn.repoze.org/repoze.bfg/ جذع / مستندات / "يختلط =" noreferrer "> توثيق سبيل المثال ).

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

Answer 2

من بيب 8:

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

• اكتب سلاسل المستندات لجميع الوحدات والوظائف والفئات والأساليب العامة.Docstrings ليست ضرورية للطرق غير العامة ، ولكن يجب أن يكون لديك تعليق يصف ما تفعله الطريقة.يجب أن يظهر هذا التعليق بعد خط "DEF".
• بيب 257 يصف اصطلاحات docstring الجيدة.لاحظ أنه الأهم من ذلك ، يجب أن تكون "" "" التي تنتهي من المستندات المتعددة على خط من تلقاء نفسها ، ويفضل أن يسبقها خط فارغ.
• بالنسبة لمستندات الخطوط الملاحية المنتظمة، لا بأس بالاحتفاظ بعلامة الإغلاق """ على نفس السطر.

Answer 3

وماذا علي أن أذهب إلى هناك:

وأي شيء لا تستطيع ان تقول من توقيع طريقة ل. في هذه الحالة بعض الشيء الوحيد المفيد هو: DISPLAYNAME - إذا فارغة سيتم تعيين لاسم الحقل

.

Answer 4

وراجع جمل التوثيق نمباي لأمثلة جيدة (مثل HTTP: / /github.com/numpy/numpy/blob/master/numpy/core/numeric.py ).

وتنقسم إلى عدة أقسام جمل التوثيق وتبدو مثل هذا:

Compute the sum of the elements of a list.

Parameters
----------
foo: sequence of ints
   The list of integers to sum up.

Returns
-------
res: int
   sum of elements of foo

See also
--------
cumsum:  compute cumulative sum of elemenents

Answer 5

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

وآخر شيء مفيد يمكنك وضعها في لجمل التوثيق الخاص بك هو doctest.

Answer 6

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

Answer 7

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