التوثيق مهم للغاية ، ليس فقط لتوصيل الهدف من الوظيفة / الفئة / الأسلوب / الوحدة إلى الآخرين ، ولكن أيضًا لنفسك.
عندما تعود إلى الكود الخاص بك بعد 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:
- Introduction to Python
- Installing Python 3 on macOS
- Running Python programs
- Python 2 vs Python 3
- The basics of working with Python
- Python Data Types
- Python Operators
- Python Strings
- Python Booleans
- Python Numbers
- Python, Accepting Input
- Python Control Statements
- Python Lists
- Python Tuples
- Python Sets
- Python Dictionaries
- Python Functions
- Python Objects
- Python Loops
- Python Modules
- Python Classes
- The Python Standard Library
- Debugging Python
- Python variables scope
- Python, accept arguments from command line
- Python Recursion
- Python Nested Functions
- Python Lambda Functions
- Python Closures
- Python Virtual Environments
- Use a GoPro as a remote webcam using Python
- Python, how to create a list from a string
- Python Decorators
- Python Docstrings
- Python Introspection
- Python Annotations
- Python, how to list files and folders in a directory
- Python, how to check if a number is odd or even
- Python, how to get the details of a file
- Python, how to check if a file or directory exists
- Python Exceptions
- Python, how to create a directory
- Python, how to create an empty file
- Python, the `with` statement
- Python, create a network request
- Python, installing 3rd party packages using `pip`
- Python, read the content of a file