教你寫出一流的python 文檔

1.為什么需要寫文檔

首先腹纳，代碼是最有意義的文檔胶坠，所有對于代碼描述的文檔主要是給：

• 不了解代碼

• 沒有時間閱讀代碼（源碼太復雜）

• 不想要閱讀源碼

• 沒有權限閱讀源碼

So don’t write clever code, write elegant code.

Code is more often read than written

當寫code時搓茬，主要有兩個觀眾寇蚊，用戶和開發(fā)者第晰。所有的觀眾都同等重要谓苟，想象一下你的用戶或者其他開發(fā)者正在經(jīng)歷和你使用其他開發(fā)者代碼的痛苦涕癣。

2.注釋和文檔的區(qū)別 Commenting 和documenting code

在介紹寫文檔之前哗蜈，我們先區(qū)分一下文檔和注釋前标。

通常，注釋主要用于描述code for developers距潘。 主要的觀眾是代碼的開發(fā)者和維護者炼列，comments 幫助讀者更好的了解代碼的目的和設計。

2.1基本的注釋：

2.1.1 注釋的主要功能

（#）????用于簡單的聲明和注釋音比，一般不超過幾句

1. 計劃和檢查：當計劃在某個位置寫代碼時俭尖，可以先用注釋聲明代碼區(qū)域和要實現(xiàn)的功能和outlining， 記得當代碼寫好之后洞翩，將這些注釋刪除稽犁。

2. 代碼描述： 解釋特定的代碼部分

3. 算法描述：當使用了算法，特別是復雜的算法骚亿，解釋算法如何工作和如何在你的代碼中應用十分重要已亥，如果可能，解釋下為何要用算法工作来屠。

4. tagging :描述已經(jīng)知道的問題或待提高的部分 如bug fixme, todo 等

2.1.2 注釋的注意事項

代碼注釋應該簡單和專注虑椎，應避免使用長的注釋。

1. 使注釋盡可能的接近代碼俱笛，注釋離代碼太遠容易讓人迷惑

2. 不要使用復雜的format 如 table 捆姜，這會導致難以維護

3. 不要包括冗余的信息

4. 為注釋設計你的代碼，設計出 easy understand concept迎膜， 讀者將會很快了解你的目的娇未，記住代碼的注釋是為其他讀者寫的，引導他們了解代碼的目的星虹。

Commenting code via type hinting 零抬，在 python 3.5 以上可以使用type hinting來為代碼寫一些注釋，包括輸入輸出的數(shù)據(jù)類型宽涌。

2.2 文檔

2.2.1 Docstrings基本描述 ：

1. Docstrings平夜，

   可以幫助使用者和自己快速了解項目，python 使用內(nèi)置的funtion help來打印出 objects的doctoring to the console卸亮。也可以使用.__doc__來查看class的注釋

2. docstring types:

   docstring 具體的要求在pep 257中描述忽妒，主要目的是提供對object的簡單描述，應該簡潔高效易維護兼贸，容易讓新的讀者了解object的目的和使用方法段直。在所有情況下docstrings 應該使用(""") 來書寫。通橙艿可以被放在一行或多行鸯檬。當有一行時，應該是一個quick summary螺垢。 當有多行時喧务，則應該包括如下部分赖歌。

   （1）一行summary

   （2）一行空行

   （3）Further elaboration

   （4）空行

3. docstring 形式

   docstring可以被分為3類，分別是class docstrings, package and module docstring 和 script docstrings.

   (1) class docstrings :class and class method

   (2) package and module docstring: package modules, functions

   (3) Script docstrings:script and functions

2.2.2 docstring 詳細介紹

2.2.2.1 Class:

主要用于class和class方法功茴。在class名稱下使用庐冯。

class docstrings 應該包含如下內(nèi)容：

(1) 目的和作用的簡介

(2) public 方法的簡單描述

(3) 類屬性

(4) 任何相關的子類

Class method 的docstring應該包含：

(1) 簡單介紹方法是什么用來做什么

(2) 參數(shù)

(3) 有默認值或者可選的參數(shù)

(4) 執(zhí)行這個方法的副作用

(5) exception

(6)使用限制

2.2.2.2 Package and module docstrings:

Module docstrings:

(1) 簡單描述模塊和目的

(2) 任何class, exception,functions,other objects exported

Module function docstring:

和class method 類似

2.2.2.3 stript docstrings:

script通常是單一的可執(zhí)行文件，script docstrings 通常在文件的最上方坎穿，并且應該告訴用戶如何使用這個腳本展父，通常應該使用 -h 可以打出需要的信息，如果使用argparse玲昧，英國對每個參數(shù)進行描述栖茉，command-line parsing libraries 包含更多的細節(jié)。

最后酌呆，任何自定義的活第三方的imports 應該在docstring中 允許用戶知道哪些包是需要用到的衡载。

可以參考numpy 或 scipy的docstings.

3. 為python projects 寫文檔

在寫python projects 的文檔時搔耕，要時刻記得誰是你的用戶隙袁，并且來滿足他們的需求，根據(jù)項目類型弃榨，一些特定的文檔是需要的菩收。

通用的項目和他的文檔應該是如下格式:

項目應該包括三個主要類型：paivate, shared public, open source.

3.1 私有 project

Readme : 簡單介紹項目和目的，包括requirements

Example.py : 使用project的例子

3.2 Shared 項目

共享項目是和其他人共享鲸睛，文檔應該要求更加嚴格娜饵，主要是幫助新的成員來這個項目或者為項目添加新東西。

Readme : 除了簡單的介紹和requirements, 還應該包括一些先前的主要版本信息官辈。

Example.py : 使用樣例箱舞。

How to contribute : 介紹新的貢獻者如何加入到這個項目中。

3.3 Public 項目：

Readme ： 簡單介紹項目和其目的拳亿，包括任何特殊的依賴包或環(huán)境晴股。另外，添加上個版本到這個版本的主要變更肺魁，另外电湘，添加練到到未來的文檔，bug 報告和其他關于這個項目的重要信息鹅经，

How to contribute : 包括新的貢獻者如何對此項目作出貢獻寂呛。包括發(fā)展新的功能，修復已有的問題瘾晃，增加文檔贷痪，新的新的測試，報告問題蹦误。

Code of conduct : 定義其他的貢獻者在開發(fā)或使用你的軟件時應該如何互相對待呢诬。

license

Docs :一個文件夾包含未來的的文檔涌哲。主要包括4個部分，分別是教程尚镰，使用案例阀圾，參考文件和解釋。

4. 如何寫docs

4.1 如何寫一個完整的docs

一個完整的docs應該包括以下幾個部分：

(1) 教程

• Learning -oriented 學習引導的

• quick start 告訴新人如何快速開始

• a lesson 是一個課程

(2) 操作指南

• 目標導向的

• 展示如何解決實際問題

• 一系列的步驟

(3) 解釋

• 理解優(yōu)先

• 解釋性

• 提供背景和具體內(nèi)容

(4) 參考文獻

• information 導向

• 描述機制

• 精確完整

詳細的內(nèi)容可以閱讀參考文獻[3]

4.2 如何寫出優(yōu)秀的docs

1. 結構簡單清晰狗唉；

   所謂結構清晰就是用戶能馬上找到自己要查找的知識點在哪初烘，分類清晰。有些文檔愛用模棱兩個的詞分俯，比如“1. 常見問題”肾筐，“2. 熱點問題”,”3. 高頻問題”。我有十萬火急的事情缸剪，你來告訴我我到底是要先看哪個吗铐？

2. 循序漸進

   先從最簡單的開始，然后慢慢深入杏节。比如我們學習Java唬渗，一開始Hello World都還沒跑起來就先說配置文件要怎么寫，Java一大堆的xml配置文件老司機都看的眼花繚亂更別說新手奋渔，這種文檔讓人直接從想了解到放棄镊逝。

3. 引人入勝

   把能吸引人的地方展示出來，比如Unity 3D默認就帶一個設計精良的游戲Demo嫉鲸，一看到就有學習的興趣撑蒜。另外提供的API應該直接能在瀏覽器里模擬出一個可調(diào)用的Demo，而不是開放的API文檔需要不停的嘗試玄渗，不停的踩坑才能調(diào)通座菠。

4. 文檔close to code and api 方便最終使用

5. 使文檔avaiable to others 通過ticketing system ，版本控制藤树，

4.3 常見的documentation工具

Sphinx,epydoc, read the docs, doxygen, mkdocs, pycoo.

5.從哪里開始寫文檔

1. 沒有文檔

2. 有一些文檔

3. 有完整的文檔

4. 好的文檔

5. 完美的文檔

如果你不知道如何開始寫浴滴，看看你在哪個位置，努力提高自己的文檔水平也榄。

最后巡莹，不要害怕寫文檔，一旦你開始寫了甜紫，很容易保持下去降宅。

Reference :

[1] https://blog.it2048.cn/article-doc-write/

[2] https://blog.jooq.org/2013/02/26/the-golden-rules-of-code-documentation/

[3] https://www.divio.com/blog/documentation/

[4] https://realpython.com/documenting-python-code/