you should write some comments in your codes
好的項(xiàng)目文檔能夠幫助人們更好的溝通：
- 對于開發(fā)者自己而言：
- 在項(xiàng)目完成后續(xù)的任何時(shí)間里，都能夠清晰的看懂之前的代碼邏輯
- 其他人通過閱讀你的代碼能夠?qū)δ銈€(gè)人能力做出判斷
- 鼓勵(lì)其他人為你的代碼做出貢獻(xiàn)
- 對于其他開發(fā)者而言：
- 其他人可以輕松使用你的代碼并以此為基礎(chǔ)繼續(xù)開發(fā)
- 對于整個(gè)社區(qū)而言：
- 推動(dòng)科學(xué)進(jìn)步
- 鼓勵(lì)開源
- 增加項(xiàng)目的可重現(xiàn)性與透明度
一份好的項(xiàng)目文檔應(yīng)該包括：
- 包含一份README文檔：
- 一個(gè)簡單的項(xiàng)目介紹
- 項(xiàng)目的安裝說明
- 簡單的使用教程
- 允許其他人反饋問題
- 寫API文檔：
- 函數(shù)的作用
- 函數(shù)的參數(shù)及其說明
- 函數(shù)的返回值
- 代碼都要寫注釋
- 闡述編碼約定杜漠，例如文件組織結(jié)構(gòu)、注釋和命名約定
- 列出所有代碼貢獻(xiàn)者
- 說明項(xiàng)目遵循的許可規(guī)則
- 給出項(xiàng)目的引用信息
- 給出項(xiàng)目負(fù)責(zé)人的聯(lián)系方式
- 列出所有的主要的歷史版本及其修改信息
一份常用的README的markdown樣例：
Project Title
------
Description
------
One Paragraph of project description goes here.
Prerequisites
------
* List all the dependencies.
* List what to install and how to install it.
Installation
------
* A step by step instructions on how to install the software.
`Example that shows how the software works.`
Contributing
------
Issue Tracker: github.com/project/issues.
License
------
Provide Licensing information.
Citation
------
* How this software can be cited.
* Provide a DOI that was generated.
Contact
------
* Link to e-mail address or URLs.
reference：
https://guides.lib.berkeley.edu/how-to-write-good-documentation
