دوكسترينغ بايثون

التوثيق مهم للغاية ، ليس فقط لتوصيل الهدف من الوظيفة / الفئة / الأسلوب / الوحدة إلى الآخرين ، ولكن أيضًا لنفسك.

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

التعليقات هي إحدى الطرق للقيام بذلك:

# this is a comment

num = 1 #this is another comment

طريقة أخرى لاستخداموثائق.

فائدة docstrings هي أنها تتبع الاصطلاحات وبالتالي يمكن معالجتها تلقائيًا.

هذه هي الطريقة التي تحدد بها docstring لوظيفة:

def increment(n):
    """Increment a number"""
    return n + 1

هذه هي الطريقة التي تحدد بها docstring لفئة وطريقة:

class Dog:
    """A class representing a dog"""
    def __init__(self, name, age):
        """Initialize a new dog"""
        self.name = name
        self.age = age
<span style="color:#66d9ef">def</span> <span style="color:#a6e22e">bark</span>(self):
    <span style="color:#e6db74">"""Let the dog bark"""</span>
    <span style="color:#66d9ef">print</span>(<span style="color:#e6db74">'WOF!'</span>)</code></pre></div>

Document a module by placing a docstring at the top of the file, for example supposing this is dog.py:

"""Dog module

This module does ... bla bla bla and provides the following classes:

- Dog
...
"""

class Dog: “”“A class representing a dog”"" def init(self, name, age): “”“Initialize a new dog”"" self.name = name self.age = age

<span style="color:#66d9ef">def</span> <span style="color:#a6e22e">bark</span>(self):
    <span style="color:#e6db74">"""Let the dog bark"""</span>
    <span style="color:#66d9ef">print</span>(<span style="color:#e6db74">'WOF!'</span>)</code></pre></div>

Docstrings can span over multiple lines:

def increment(n):
    """Increment
    a number
    """
    return n + 1

Python will process those and you can use the help() global function to get the documentation for a class/method/function/module.

For example calling help(increment) will give you this:

Help on function increment in module
__main__:

increment(n) Increment a number

There are many different standards to format docstrings, and you can choose to adhere to your favorite one.

I like Google’s standard: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings

Standard allows to have tools to extract docstrings and automatically generate documentation for your code.


More python tutorials: