مستند سازی کد پایتون

به راهنمای کامل خود برای مستندسازی کد پایتون خوش آمدید. این که آیا شما در حال مستندسازی یک اسکریپت کوچک یا یک پروژه بزرگ هستید، چه یک مبتدی و چه یک پایتونی با تجربه هستید، این راهنما همه چیزهایی را که باید بدانید پوشش می دهد.

 #  چرا مستند سازی کد مهم است؟

امیدوارم اگر این آموزش را می خوانید، از قبل اهمیت مستندسازی کد خود را می دانید. اما اگر نه، بگذارید چیزی را نقل کنم که Guido در PyCon اخیر اشاره کرد:  کد بیشتر از آنکه نوشته شود خوانده می شود.

شما هنگام نوشتن کد، آن را برای دو مخاطب اصلی می نویسید: کاربران و توسعه دهندگان(از جمله خود شما). هر دو مخاطب از اهمیت یکسانی برخوردارند. اگر شما هم مثل من هستید، احتمالاً پایگاه های کد قدیمی را باز کرده اید و با خود فکر کرده اید: "من در زمان نوشتن این کد به چه فکر می کردم؟" اگر در خواندن کد خود مشکل دارید، تصور کنید کاربران یا توسعه دهندگان دیگر هنگام استفاده از کد یا مشارکت در کد شما چه چیزی را تجربه می کنند.

برعکس، من مطمئن هستم که شما در موقعیتی قرار گرفته اید که می خواهید کاری در پایتون انجام دهید و به نظر می رسد که یک کتابخانه عالی به نظر می رسد که می تواند کار را انجام دهد. با این حال، هنگامی که شروع به استفاده از کتابخانه می کنید، به دنبال مثال ها، نوشته ها یا حتی اسناد رسمی در مورد چگونگی انجام کار خاص هستید و نمی توانید بلافاصله راه حل را پیدا کنید.

پس از جستجو، متوجه می شوید که اسناد موجود نیست یا حتی بدتر از آن، به طور کامل گم شده است. این احساس ناامیدکننده ای است که شما را از استفاده از کتابخانه، صرفنظر از میزان عالی یا کارآمدی کد، باز می دارد.

در این راهنما، شما از ابتدا یاد می گیرید که چگونه کد پایتون خود را از کوچکترین اسکریپت ها تا بزرگترین پروژه های پایتون به درستی مستند کنید تا به کاربران خود کمک کنید تا از پروژه شما استفاده کنند.

مقاله مرتبط: آموزش نوشتن کامنت در پایتون

 #  کامنت گذاری در مقابل مستند سازی

قبل از اینکه بتوانیم نحوه مستندسازی کد پایتون را بررسی کنیم، باید مستندسازی را از کامنت گذاری تشخیص دهیم.

به طور کلی،کامنت گذاری توصیف کد شما برای توسعه دهندگان است. مخاطب اصلی مورد نظر، توسعه دهندگان کد پایتون هستند. همراه با کد خوب نوشته شده، نظرات به خواننده کمک می کند تا کد شما و هدف و طراحی آن را بهتر بشناسد. کد به شما میگوید چطور، کامنت میگوید چگونه.

مستندسازی کد استفاده و عملکرد آن را برای کاربران شما شرح می دهد. در حالی که ممکن است در روند توسعه مفید باشد، مخاطبان اصلی مورد نظر کاربران هستند. بخش زیر نحوه و زمان نظر دادن کد شما را توضیح می دهد.

 +  مقدمات کامنت نویسی

نظرات با استفاده از علامت پوند (#) در پایتون ایجاد می شود و باید جملات مختصر بیش از چند جمله نباشد. در اینجا یک مثال ساده است:

def hello_world():
    # A simple comment preceding a simple print statement
    print("Hello World")

طبق PEP 8، نظرات باید حداکثر 72 کاراکتر داشته باشند. این حتی اگر پروژه شما حداکثر طول خط را به بیش از 80 کاراکتر توصیه شده تغییر دهد، صادق است. اگر یک کامنت بیشتر از حد مجاز نظر باشد، استفاده از چندین خط برای کامنت مناسب است:

def hello_long_world():
    # A very long statement that just goes on and on and on and on and
    # never ends until after it's reached the 80 char limit
    print("Hellooooooooooooooooooooooooooooooooooooooooooooooooooooooo World")

کامنت نویسی کد شما اهداف مختلفی دارد، از جمله:

 -  برنامه‌ریزی و بازبینی: هنگامی که بخش جدیدی از کد خود را ایجاد می کنید، ممکن است مناسب باشد که ابتدا از کامنت به عنوان راهی برای برنامه ریزی یا طرح آن بخش کد استفاده کنید. به یاد داشته باشید که این کامنت ها را پس از پیاده سازی واقعی و بررسی/آزمایش حذف کنید:

# First step
# Second step
# Third step

 -  توصیف کد: از کامنت‌ها می توان برای توضیح منظور بخش های خاصی از کد استفاده کرد:

# Attempt a connection based on previous settings. If unsuccessful,
# prompt user for new settings.

 -  توصیف الگوریتم: هنگامی که از الگوریتم ها استفاده می شود، به ویژه الگوریتم های پیچیده، توضیح نحوه کار الگوریتم یا نحوه اجرای آن در کد شما می تواند مفید باشد. همچنین ممکن است توضیح دهد که چرا یک الگوریتم خاص بر الگوریتم دیگری انتخاب شده است.

# Using quick sort for performance gains

 -  تگ‌گذاری: استفاده از تگ‌گذاری می تواند برای برچسب گذاری بخش های خاصی از کد که در آن مسائل یا نواحی بهبود یافته قرار دارند، استفاده شود. برخی از نمونه ها عبارتند از: BUG ، FIXME و TODO.

# TODO: Add condition for when val is None

کامنت‌های مربوط به کد شما باید مختصر و متمرکز باشد. در صورت امکان از استفاده از کامنت‌های طولانی خودداری کنید. علاوه بر این، شما باید از چهار قانون اساسی زیر که توسط جف اتوود پیشنهاد شده است استفاده کنید:

1. تا جایی که ممکن است کامنت‌ها را نزدیک به کدی که توصیف می شود نگه دارید. کامنت‌هایی که نزدیک به کد توصیف آنها نیست برای خواننده ناامید کننده است و در هنگام انجام به روز رسانی به راحتی از دست می رود.

2. از قالب بندی پیچیده (مانند جداول یا ارقام ASCII) استفاده نکنید. قالب بندی پیچیده منجر به حواس پرتی می شود و حفظ آن در طول زمان دشوار است.

3. اطلاعات اضافی وارد نکنید. فرض کنید خواننده کد دارای درک اساسی از اصول برنامه نویسی و نحو زبان است.

4. کد خود را طوری طراحی کنید که خود توضیح باشد. ساده ترین راه برای درک کد خواندن آن است. هنگامی که کد خود را با استفاده از مفاهیم واضح و قابل فهم طراحی می کنید، خواننده می تواند به سرعت قصد شما را مفهوم سازی کند.

به یاد داشته باشید که کامنت‌ها برای خواننده، از جمله خود شما طراحی شده است تا به آنها در درک هدف و طراحی نرم افزار کمک کند.

مقاله پیشنهادی: متد append پایتون

 +  کامنت‌گذاری کد با استفاده از Type hint(پایتون 3.5 به بالا)

Type hinting به پایتون 3.5 اضافه شد و یک فرم اضافی برای کمک به خوانندگان کد شما است. در واقع، چهارمین پیشنهاد جف را از بالا به سطح بعدی می برد. این به توسعه دهنده اجازه می دهد بخش هایی از کد خود را بدون کامنت طراحی و توضیح دهد. در اینجا یک مثال سریع وجود دارد:

def hello_name(name: str) -> str:
    return(f"Hello {name}")

با بررسی Type hinting، می توانید بلافاصله بگویید که تابع انتظار دارد نام ورودی از نوع str یا رشته باشد. همچنین می توانید بگویید که خروجی مورد انتظار تابع نیز از نوع str یا string خواهد بود. در حالی که Type hinting به کاهش کامنت کمک می کند، در نظر داشته باشید که انجام این کار هنگام ایجاد یا به روز رسانی اسناد پروژه شما ممکن است کار بیشتری برایتان داشته باشد.

ویدیو مرتبط: ویدیو آموزش annotations در پایتون

 #  مستند سازی با docstring

اکنون که درباره کامنت آموختیم، بیایید در زمینه مستند سازی پایگاه پایتون یک حرکت عمیق انجام دهیم. در این بخش، شما با docstring و نحوه استفاده از آنها برای مستندسازی آشنا خواهید شد.

 +  سابقه و هدف docstring

مستند سازی کد پایتون شما همگی بر روی docstrings متمرکز شده است. اینها رشته های داخلی هستند که اگر به درستی پیکربندی شوند، می توانند به اسناد پروژه شما، به کاربران و خود شما کمک کنند. پایتون همراه با تابع docstrings همچنین دارای تابع help() است که اشیاء docstring را روی کنسول چاپ می کند. در اینجا یک مثال سریع وجود دارد:

>>> help(str)
Help on class str in module builtins:

class str(object)
 |  str(object='') -> str
 |  str(bytes_or_buffer[, encoding[, errors]]) -> str
 |
 |  Create a new string object from the given object. If encoding or
 |  errors are specified, then the object must expose a data buffer
 |  that will be decoded using the given encoding and error handler.
 |  Otherwise, returns the result of object.__str__() (if defined)
 |  or repr(object).
 |  encoding defaults to sys.getdefaultencoding().
 |  errors defaults to 'strict'.
 # Truncated for readability

این خروجی چگونه تولید می شود؟ از آنجا که همه چیز در پایتون یک شی است، می توانید فهرست دستورات را با استفاده از دستور dir() بررسی کنید. بیایید این کار را انجام دهیم و ببینیم چه چیزی پیدا می شود:

>>> dir(str)
['__add__', ..., '__doc__', ..., 'zfill'] # Truncated for readability

در آن خروجی فهرست، یک ویژگی جالب، __doc__ وجود دارد. اگر آن ویژگی را بررسی کنید، این را کشف خواهید کرد:

>>> print(str.__doc__)
str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors are specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.

شما جایی را پیدا کرده اید که رشته های سند در شیء ذخیره می شوند. این بدان معناست که می توانید مستقیماً آن ویژگی را دستکاری کنید. با این حال، محدودیت هایی برای buildins وجود دارد:

>>> str.__doc__ = "I'm a little string doc! Short and stout; here is my input and print me for my out"
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: can't set attributes of built-in/extension type 'str'

هر شی سفارشی دیگر را می توان دستکاری کرد:

def say_hello(name):
    print(f"Hello {name}, is it me you're looking for?")

say_hello.__doc__ = "A simple function that says hello... Richie style"

>>> help(say_hello)
Help on function say_hello in module __main__:

say_hello(name)
    A simple function that says hello... Richie style

پایتون یک ویژگی دیگر نیز دارد که ایجاد docstring را ساده می کند. به جای دستکاری مستقیم در ویژگی __doc__ ، قرار دادن استراتژیک رشته به معنای واقعی کلمه در زیر شیء به طور خودکار مقدار __doc__ را تعیین می کند. در اینجا همان چیزی است که با همان مثال بالا اتفاق می افتد:

def say_hello(name):
    """A simple function that says hello... Richie style"""
    print(f"Hello {name}, is it me you're looking for?")

>>> help(say_hello)
Help on function say_hello in module __main__:

say_hello(name)
    A simple function that says hello... Richie style

اکنون شما پیشینه رشته های docstrings را درک کرده اید. اکنون وقت آن است که در مورد انواع مختلف docstring و اطلاعاتی که باید در آنها وجود داشته باشد، بیاموزید.

ویدیو مرتبط: ویدیو توضیح docstring در پایتون

 +  انواع docstring

قواعد Docstring در PEP 257 شرح داده شده است. هدف آنها ارائه یک مرور کلی اجمالی به کاربران است. آنها باید به اندازه کافی مختصر نگه داشته شوند تا نگهداری آنها آسان باشد، اما هنوز به اندازه کافی مفصل هستند تا کاربران جدید بتوانند منظور خود و نحوه استفاده از شیء مستند را درک کنند.

در همه موارد، رشته های docstring باید از قالب رشته double-quote ("" ") استفاده کنند. این کار باید انجام شود اعم از اینکه docstring چند خط است یا خیر. در حداقل، یک docstring باید خلاصه ای سریع از هر چیزی باشد که توصیف می کنید و باید در یک خط واحد قرار گیرد:

"""This is a quick summary line used as a description of the object."""

رشته های چند خطی برای توضیح بیشتر در مورد شی فراتر از خلاصه استفاده می شود. همه رشته های چند خطی دارای قسمت های زیر هستند:

• یک خط خلاصه
• یک خط خالی بعد از خلاصه
• هرگونه توضیح بیشتر برای رشته docstring
• یک خط خالی دیگر

"""This is the summary line

This is the further elaboration of the docstring. Within this section,
you can elaborate further on details as appropriate for the situation.
Notice that the summary and the elaboration is separated by a blank new
line.
"""

# Notice the blank line above. Code should continue on this line.

همه docstringها باید حداکثر طول کاراکترهای کامنت‌ها (72 کاراکتر) را داشته باشند. Docstrings را می توان به سه دسته عمده تقسیم کرد:

• Class Docstrings: رشته‌های مربوط به کلاس‌ها و متدها
• Package and Module Docstrings: رشته‌های مربوط به پکیج، ماژول و فانکشن‌ها
• Script Docstrings: رشته‌های مربوط به اسکریپت‌ها و فانکشن‌ها

مقاله پیشنهادی: تفاوت بین ماژول، پکیج، لایبرری و فریمورک در پایتون

 +  class docstring

Class Docstrings برای کلاس و همچنین هر متد کلاس ایجاد می شود. خطوط اسناد بلافاصله به دنبال کلاس یا متد کلاس که در یک سطح مشخص شده اند قرار می گیرند:

class SimpleClass:
    """Class docstrings go here."""

    def say_hello(self, name: str):
        """Class method docstrings go here."""

        print(f'Hello {name}')

Class Docstrings باید حاوی اطلاعات زیر باشد:

• خلاصه ای از هدف و رفتار آن
• هر متد عمومی، همراه با توضیح مختصر
• هر ویژگی کلاس (attributes)
• هر چیزی که مربوط به رابط کاربری برای زیرکلاس ها باشد، در صورتی که کلاس زیر کلاس باشد

پارامترهای سازنده کلاس باید در docstring متد __init__ ثبت شوند. متدهای دیگر باید با استفاده از docstring خود مستند شوند. رشته های docstrings باید شامل موارد زیر باشد:

• شرح مختصری از روش و کاربرد آن
• هرگونه آرگومان (اعم از الزامی و اختیاری) که شامل آرگومان های کلید واژه می شود
• آرگومان هایی را که اختیاری تلقی می شوند یا دارای مقدار پیش فرض هستند، برچسب گذاری کنید
• هرگونه عوارض جانبی که هنگام اجرای متد ایجاد می شود
• هرگونه استثنائاتی که مطرح می شود
• هرگونه محدودیت در مورد زمان فراخوانی متد

بیایید یک مثال ساده از یک کلاس داده که نمایانگر یک حیوان است، بیاوریم. این کلاس شامل چند ویژگی کلاس، ویژگی های نمونه، __init__ و یک متد instance است:

class Animal:
    """
    A class used to represent an Animal

    ...

    Attributes
    ----------
    says_str : str
        a formatted string to print out what the animal says
    name : str
        the name of the animal
    sound : str
        the sound that the animal makes
    num_legs : int
        the number of legs the animal has (default 4)

    Methods
    -------
    says(sound=None)
        Prints the animals name and what sound it makes
    """

    says_str = "A {name} says {sound}"

    def __init__(self, name, sound, num_legs=4):
        """
        Parameters
        ----------
        name : str
            The name of the animal
        sound : str
            The sound the animal makes
        num_legs : int, optional
            The number of legs the animal (default is 4)
        """

        self.name = name
        self.sound = sound
        self.num_legs = num_legs

    def says(self, sound=None):
        """Prints what the animals name is and what sound it makes.

        If the argument `sound` isn't passed in, the default Animal
        sound is used.

        Parameters
        ----------
        sound : str, optional
            The sound the animal makes (default is None)

        Raises
        ------
        NotImplementedError
            If no sound is set for the animal or passed in as a
            parameter.
        """

        if self.sound is None and sound is None:
            raise NotImplementedError("Silent Animals are not supported!")

        out_sound = self.sound if sound is None else sound
        print(self.says_str.format(name=self.name, sound=out_sound))

دوره پیشنهادی: دوره آموزش پایتون (python)

 +  package and module docstring

رشته های پکیج باید در بالای فایل __init__.py بسته قرار گیرند. این docstring باید ماژول ها و زیر-پکیج هایی را که توسط پکیج صادر می شوند، لیست کند.

رشته های ماژول شبیه به رشته های کلاس هستند. به جای اینکه کلاسها و متدهای کلاس مستند شوند، اکنون ماژول و هرگونه توابع موجود در آن مستند میشوند. رشته های ماژول حتی قبل از هرگونه import در بالای فایل قرار می گیرند. رشته های ماژول باید شامل موارد زیر باشد:

• شرح مختصری از ماژول و هدف آن
• لیستی از هر کلاس، استثنا، توابع و سایر اشیاء صادر شده توسط ماژول

رشته docsting برای یک تابع ماژول باید شامل موارد مشابه یک متد کلاس باشد:

• شرح مختصری از عملکرد و کاربرد آن
• هرگونه آرگومان (اعم از الزامی و اختیاری) که شامل آرگومان های کلید واژه می شود
• هرگونه آرگومان را که اختیاری تلقی می شود برچسب گذاری کنید
• هرگونه عوارض جانبی که هنگام اجرای فانکشن رخ می دهد
• هرگونه استثنائاتی که مطرح می شود
• هرگونه محدودیت در مورد زمان فراخوانی فانکشن

مقاله پیشنهادی: چطور اسکریپت های پایتون را اجرا کنیم؟

 +  script docstring

اسکریپت ها به عنوان فایل های اجرایی تک فایل اجرا شده از کنسول در نظر گرفته می شوند. رشته های اسکریپت در بالای فایل قرار می گیرند و باید به اندازه کافی مستند باشند تا کاربران بتوانند درک کافی از نحوه استفاده از اسکریپت داشته باشند. هنگامی که کاربر به طور نادرست از یک پارامتر عبور می کند یا از گزینه -h استفاده می کند، باید برای پیام "usage" آن قابل استفاده باشد.

اگر از argparse استفاده می کنید ، می توانید اسناد مربوط به پارامتر را حذف کنید ، با این فرض که به درستی در پارامتر راهنمای تابع argparser.parser.add_argument ثبت شده باشد. توصیه می شود از __doc__ برای پارامتر description در سازنده argparse.ArgumentParser استفاده کنید.

سرانجام، هرگونه import سفارشی یا شخص ثالث باید در رشته ها ذکر شود تا کاربران بدانند چه بسته هایی برای اجرای اسکریپت مورد نیاز است. در اینجا نمونه ای از اسکریپت است که برای چاپ سرصفحه های صفحه گسترده استفاده می شود:

"""Spreadsheet Column Printer

This script allows the user to print to the console all columns in the
spreadsheet. It is assumed that the first row of the spreadsheet is the
location of the columns.

This tool accepts comma separated value files (.csv) as well as excel
(.xls, .xlsx) files.

This script requires that `pandas` be installed within the Python
environment you are running this script in.

This file can also be imported as a module and contains the following
functions:

    * get_spreadsheet_cols - returns the column headers of the file
    * main - the main function of the script
"""

import argparse

import pandas as pd


def get_spreadsheet_cols(file_loc, print_cols=False):
    """Gets and prints the spreadsheet's header columns

    Parameters
    ----------
    file_loc : str
        The file location of the spreadsheet
    print_cols : bool, optional
        A flag used to print the columns to the console (default is
        False)

    Returns
    -------
    list
        a list of strings used that are the header columns
    """

    file_data = pd.read_excel(file_loc)
    col_headers = list(file_data.columns.values)

    if print_cols:
        print("\n".join(col_headers))

    return col_headers


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        'input_file',
        type=str,
        help="The spreadsheet file to pring the columns of"
    )
    args = parser.parse_args()
    get_spreadsheet_cols(args.input_file, print_cols=True)


if __name__ == "__main__":
    main()

مقاله پیشنهادی: مهم ترین تابع‌ های پایتون که باید بدانید

 +  قالب‌های docstring

شاید متوجه شده باشید که در مثال هایی که در این آموزش آورده شده، قالب بندی خاصی با عناصر مشترک وجود داشته است: Arguments ، Returns و Attributes. فرمت های خاص docstrings وجود دارد که می تواند برای تجزیه و تحلیل docstring مورد استفاده قرار گیرد و کاربران یک قالب آشنا و شناخته شده داشته باشند. قالب بندی مورد استفاده در مثال های این آموزش، فایل های docstrings به سبک NumPy/SciPy است.

انتخاب قالب docstring به عهده خود شماست ، اما باید در تمام سند/پروژه خود از همان فرمت استفاده کنید. در زیر نمونه هایی از هر نوع آورده شده است تا تصویری از ظاهر هر فرمت اسناد به شما ارائه شود. برخی از رایج ترین فرمت ها به شرح زیر است:

Google Docstrings Example

"""Gets and prints the spreadsheet's header columns

Args:
    file_loc (str): The file location of the spreadsheet
    print_cols (bool): A flag used to print the columns to the console
        (default is False)

Returns:
    list: a list of strings representing the header columns
"""

reStructured Text Example

"""Gets and prints the spreadsheet's header columns

:param file_loc: The file location of the spreadsheet
:type file_loc: str
:param print_cols: A flag used to print the columns to the console
    (default is False)
:type print_cols: bool
:returns: a list of strings representing the header columns
:rtype: list
"""

NumPy/SciPy Docstrings Example

"""Gets and prints the spreadsheet's header columns

Parameters
----------
file_loc : str
    The file location of the spreadsheet
print_cols : bool, optional
    A flag used to print the columns to the console (default is False)

Returns
-------
list
    a list of strings representing the header columns
"""

Epytext Example

"""Gets and prints the spreadsheet's header columns

@type file_loc: str
@param file_loc: The file location of the spreadsheet
@type print_cols: bool
@param print_cols: A flag used to print the columns to the console
    (default is False)
@rtype: list
@returns: a list of strings representing the header columns
"""

 #  مستند سازی پروژه پایتونی

پروژه های پایتون دارای انواع مختلفی از اشکال، اندازه ها و اهداف هستند. نحوه ثبت پروژه شما باید متناسب با شرایط خاص شما باشد. به خاطر داشته باشید که کاربران پروژه شما چه کسانی هستند و با نیازهای آنها سازگار هستند. بسته به نوع پروژه، جنبه های خاصی از مستندات توصیه می شود. طرح کلی پروژه و مستندات آن باید به شرح زیر باشد:

project_root/
│
├── project/  # Project source code
├── docs/
├── README
├── HOW_TO_CONTRIBUTE
├── CODE_OF_CONDUCT
├── examples.py

پروژه ها را می توان به سه نوع عمده تقسیم کرد: خصوصی ، مشترک و عمومی/منبع باز.

 +  پروژه‌های شخصی

پروژه های خصوصی پروژه هایی هستند که فقط برای استفاده شخصی در نظر گرفته شده اند و عموماً با سایر کاربران یا توسعه دهندگان به اشتراک گذاشته نمی شوند. اسناد و مدارک می تواند برای این نوع پروژه ها بسیار روشن باشد. برخی از قسمتهای توصیه شده برای اضافه کردن در صورت نیاز وجود دارد:

• Readme: خلاصه ای از پروژه و هدف آن. الزامات خاصی را برای نصب یا راه اندازی پروژه در نظر بگیرید.
• examples.py: یک فایل اسکریپت پایتون که نمونه های ساده ای از نحوه استفاده از پروژه را ارائه می دهد.

به یاد داشته باشید، اگرچه پروژه های خصوصی برای شخص شما در نظر گرفته شده است، اما شما نیز یک کاربر محسوب می شوید. در مورد هر چیزی که ممکن است برای شما گیج کننده باشد در طول راه فکر کنید و مطمئن شوید که آنها را در کامنت‌ها، docstrings یا readme یادداشت کنید.

 +  پروژه‌های مشترک

پروژه های مشترک پروژه هایی هستند که در آنها با چند نفر دیگر در توسعه و/یا استفاده از پروژه همکاری می کنید. "مشتری" یا کاربر پروژه همچنان شما هستید و تعداد محدودی که از پروژه نیز استفاده می کنند.

مستندسازی باید کمی دقیق تر از آنچه برای یک پروژه خصوصی لازم است باشد، عمدتا برای کمک به اعضای جدید پروژه یا هشدار به مشارکت کنندگان/کاربران در مورد تغییرات جدید در پروژه. برخی از قسمتهای توصیه شده برای افزودن به پروژه به شرح زیر است:

• Readme: خلاصه ای از پروژه و هدف آن. الزامات خاصی را برای نصب یا راه اندازی پروژه در نظر بگیرید. علاوه بر این ، تغییرات عمده را نسبت به نسخه قبلی اضافه کنید
• examples.py: یک فایل اسکریپت پایتون که نمونه های ساده ای از نحوه استفاده از پروژه ها را ارائه می دهد.
• How to Contribute: این باید شامل چگونگی مشارکت مشارکت کنندگان جدید در پروژه باشد.

 +  پروژه‌های عمومی/منبع باز

پروژه های عمومی و منبع باز پروژه هایی هستند که قرار است با گروه زیادی از کاربران به اشتراک گذاشته شوند و می توانند تیم های توسعه بزرگ را درگیر کنند. این پروژه ها باید به اندازه توسعه واقعی خود پروژه، بر اسناد پروژه از اولویت برخوردار باشند. برخی از قسمتهای توصیه شده برای افزودن به پروژه به شرح زیر است:

• Readme: خلاصه ای از پروژه و هدف آن. شامل هرگونه الزامات خاص برای نصب یا راه اندازی پروژه ها. علاوه بر این ، تغییرات عمده را نسبت به نسخه قبلی اضافه کنید. در نهایت ، پیوندهایی را به اسناد بیشتر ، گزارش اشکال و هرگونه اطلاعات مهم دیگر برای پروژه اضافه کنید.
• How to Contribute: این شامل نحوه کمک به مشارکت کنندگان جدید پروژه می شود. این شامل توسعه ویژگی های جدید ، رفع مشکلات شناخته شده ، افزودن مستندات ، افزودن آزمایش های جدید یا گزارش مشکلات است.
• Code of Conduct: نحوه برخورد سایر مشارکت کنندگان هنگام توسعه یا استفاده از نرم افزار شما را با یکدیگر مشخص می کند. این همچنین بیان می کند که اگر این کد خراب شود چه اتفاقی می افتد. اگر از Github استفاده می کنید، می توانید الگوی کد رفتار را با عبارت توصیه شده ایجاد کنید. مخصوصاً برای پروژه های منبع باز ، این را اضافه کنید
• License: یک فایل متنی ساده که مجوز پروژه شما را نشان می دهد. مخصوصاً برای پروژه های منبع باز ، این را اضافه کنید.
• docs: پوشه ای که حاوی مستندات بیشتری است.

 #  نتیجه گیری

مستندسازی پروژه ها پیشرفت ساده ای دارد:

1. بدون مستندات
2. مستندات کم
3. مستندات کامل
4. مستندات خوب
5. مستندات عالی

در پایان، از میزان کار مورد نیاز برای مستندسازی کد دلسرد نشوید. هنگامی که شروع به مستندسازی کد خود کردید، ادامه راه آسان تر می شود.