科學軟體十條簡單程式設計原則

規則1：在編碼時編寫註釋
註釋是軟體文件中最重要的一個方面。在一天結束時，人們（包括您自己）需要能夠閱讀和理解您的原始碼。好的變數和函式名稱可以極大地提高可讀性，儘管它們不能完全替代註釋。雖然你的程式碼在沒有評論的情況下可能會很明顯，但其他讀者可能不會那麼幸運。實際上，在您轉移到另一個專案之後，您自己可能甚至無法理解您自己的程式碼。將註釋解釋視為您的實驗室筆記本：它們可以幫助您在事後很久就記住您的思路。
編寫註釋的最佳方法是在編寫程式碼時執行此操作。這樣你永遠不會忘記你的思維過程是什麼，你永遠不會忘記回去寫你自己承諾的評論（我們都對此感到內疚）。現代整合開發環境（IDE）通常會在您編寫程式碼時自動生成文件字串，從而消除了必須記住編寫註釋的負擔。反對徹底的程式碼評論的一個常見論點是它會減慢你的速度。事實上，良好的評論可以幫助您更快地編寫程式碼，因為您可以更好地瞭解您的軟體。當您遇到錯誤時，這種理解特別有用，因為您可以將您的程式碼正在做的事情與您的評論所說的應該做的事情進行比較。
正確的程式碼評論既是一門藝術，也是一門科學。如果您寫的評論太少，人們將無法弄清楚您的程式碼在做什麼。寫得太多，讀者會在評論的海洋中迷失。作為指導原則，旨在編寫讀者可以透過閱讀您的評論來理解的程式碼。

規則2：包含示例（以及大量示例）
說到軟體文件，示例優先於說明。除簡單說明外，在文件中包含示例有幾個重要原因。
Keras是一個機器學習框架，截至撰寫本文時，它有35個完整的示例指令碼（github.com/keras-team/keras/tree/master/examples），帶有自述檔案（詳見規則4），解釋每個示例演示。儘管您沒有義務提供這麼多示例，但請花時間至少編寫一些示例來展示您軟體的主要功能。您甚至可以使您的示例作為單元測試執行雙重任務（反之亦然），從而在提供指令時驗證功能。

規則3：包括快速入門指南
儘快實現從想法到實驗再到結果，可以促進科學的進步。如果人們花了很長時間來弄清楚如何使用你的軟體，他們可能會放棄。相反，如果人們可以立即開始使用您的工具，他們就更有可能將其作為研究的一部分。因此，必須包含一個快速入門指南，旨在幫助人們儘快開始使用您的軟體。

例如，讓我們看一下TPOT機器學習工具的快速入門指南：它有一個顯示軟體功能的動畫圖形影像檔案（GIF），解釋它如何工作的圖表，以及一個最小的程式碼存根，非常適合複製貼上到你自己的專案。要判斷您的快速入門指南是否按預期工作，請將其顯示給未使用過您軟體的人，看看他們是否可以找出如何開始使用它。考慮一下你的快速入門指南，作為你專案的約會檔案：它應該展示它的優勢，給人一種感覺，並誘使人們選擇它。

規則4：包含帶有基本資訊的README檔案
您的README檔案就像是專案的主頁。在GitHub，Bitbucket和GitLab等程式碼共享站點上，您的README檔案顯示在專案的主頁面上。README檔案應該可以從原始源輕鬆讀取，因此人類可讀的標記語言（如Markdown或reStructuredText（或純文字））比不太可讀的格式（如超文字標記語言（HTML））更可取。事實上，程式碼共享站點通常會在您的儲存庫頁面上呈現您的標記語言，為您提供兩全其美的優勢。利用這種免費託管是很難得到的，而且託管的README頁面在您的儲存庫中，這使得安排更加甜蜜。

一個好的經驗法則是假設README中包含的資訊將是使用者閱讀的唯一文件。因此，您的自述檔案應包括如何安裝和配置軟體，在何處查詢完整文件，在何處釋出許可證，如何測試以確保功能以及確認。此外，您應該在自述檔案中包含快速入門指南（如規則3中所述）。

通常，自述檔案頂部會包含徽章，這些徽章在呈現時會顯示軟體的狀態。徽章的一個常見來源是shields.io，它可以為您的專案動態生成徽章。常見徽章包括顯示自動化測試是否正在傳遞的徽章（例如來自travis-ci.org的徽章），測試覆蓋的程式碼百分比，文件是否是最新的等等。雖然沒有必要，但這些徽章會使您對專案質量充滿信心，並且一目瞭然地傳達重要資訊，因此強烈建議使用。

規則5：包含命令列介面的幫助命令
許多科學軟體工具都有命令列介面（CLI）。沒有圖形介面可以節省開發時間並使軟體更加靈活。然而，CLI軟體面臨的一個挑戰是很難弄清楚如何使用。記錄CLI的最佳方法是使用“幫助”命令列印出如何使用該軟體。這樣，使用者無需嘗試查詢文件即可完成基本任務。它應該包括用法（如何使用命令），子命令（如果適用），選項和/或引數，環境變數（如果適用），甚至可能包括一些示例（規則2再次發生！）。
幫助命令可能很難製作並且難以維護，但幸運的是有許多軟體包可以為您完成。在Python中，click（click.pocoo.org）等軟體不僅可以提供幫助命令，還可以幫助您建立介面，從而節省您的時間和精力。
良好的CLI的一個例子是Magic-BLAST中包含的CLI。它有一個簡短的幫助命令“-h”，它提供有關工具是什麼以及如何使用它的基本資訊。它還包括有關如何訪問完整幫助文件的說明，其中包括每個選項的列表以及選項引數的說明及其作用。這樣的安排特別好，因為它只需要很少的努力就可以透過簡短的幫助頁面找到最有用的資訊，從而減少資訊過載並透過提供如何訪問完整CLI參考的提醒來減少使用軟體的認知負擔。

規則6：版本控制您的文件
首先，您應該將文件與其他檔案一起儲存在Git儲存庫中。這使您可以在專案歷史中的任何位置檢視文件。Read the Docs（readthedocs.org）和Zenodo（zenodo.org）等服務使這一過程變得更加容易，因為每次製作軟體的新版本時，它們都會存檔文件的完整渲染版本。
為了說明為什麼這是一個如此重要的規則，請考慮如果更改軟體新版本中的預設設定會發生什麼。當以前版本的使用者檢視您的文件時，他們將看到與他們已安裝的版本不相容的文件。更糟糕的是，因為您更改了預設設定，軟體可能會莫名其妙地失敗。這可能會讓使用者感到非常惱火（如果軟體適用於任務關鍵型應用程式，甚至會很危險），因此對文件使用版本控制尤為重要。文件中的更改日誌可以使此任務更容易。如果您正在使用提供資訊的提交訊息，那麼建立更改日誌在最壞的情況下是一項簡單的任務，而且最多也是一項微不足道的任務。

作為生物資訊學庫的一個例子，它在控制文件的版本方面做得特別好，請檢視khmer，它有一個包含新功能的徹底更改日誌，修復了錯誤（由它們是否與使用者或開發人員相關），已知問題，以及釋出的貢獻者列表。此外，文件網站的早期版本可以輕鬆訪問並標記清楚。透過提供此資訊，作者確保任何版本軟體的使用者都可以獲得正確版本的文件，檢視專案中發生的情況，並確保他們瞭解其版本的任何問題。
如果您對此規則不以為然，請清楚說明您的文件適用於哪個版本的軟體，並保留以前版本的文件 - 您的使用者將會感謝您。

規則7：完整記錄您的應用程式程式設計介面
您的應用程式程式設計介面（API）是使用您的軟體的人與您的程式碼互動的方式。它必須在原始碼中完整記錄。老實說，可能沒人會讀你的整個API文件，這很好。API文件的目標是防止使用者不得不深入挖掘您的原始碼以使用您的API。至少，每個函式都應記錄其輸入和輸入型別，記錄其輸出和輸出型別，以及記錄的任何錯誤。物件應該描述它們的方法和屬性。最好為API文件使用一致的樣式。

Google風格指南（google.github.io/styleguide）有許多語言的API文件建議，如Python，Java，R，C ++和Shell。您花了很多時間開發API; 不要告訴使用者如何使用它，不要浪費時間。

規則8：使用自動化文件工具
最好的文件型別是自己編寫的文件。雖然沒有任何軟體包可以為您完成所有文件，但有些工具可以解決大部分問題，例如建立網站，使其與程式碼保持同步，以及將其呈現為可移植文件檔案（ PDF）。

R的Sphinx（sphinx-doc.org），perldoc，Javadoc和Roxygen（https://github.com/klutometis/roxygen）等軟體可以生成文件，甚至可以閱讀您的註釋並使用它們生成詳細的API文件。

儘管Sphinx是為了託管Python的文件而開發的，但它與語言無關，這意味著它可以適用於您的專案所使用的任何語言。同樣，Doxygen（doxygen.nl）和MkDocs（mkdocs.org））是與語言無關的文件工具。閱讀規則6中介紹的文件是一個與語言無關的文件託管平臺，可以在每次推送到儲存庫時重建文件，確保您的文件始終是最新的。

自動化還有許多其他方法可以使您的文件變得更加智慧：在Python中，像doctest這樣的軟體（sphinx-doc.org/en/stable/ext/doctest.html）可以自動從您的文件中提取示例並確保您的程式碼能夠完成您的工作。

為了幫助您遵循規則7，有一些工具，如Napoleon（github.com/sphinx-contrib/napoleon），可以為您生成API文件。甚至可以使用諸如Swagger（swagger.io）之類的免費工具自動生成互動式代表性狀態轉移（REST）API文件。此時，幾乎沒有理由不使用自動化文件工具。

規則9：編寫提供解決方案或指向文件的錯誤訊息
在開發軟體時，錯誤訊息是生活的一部分。作為開發人員，您應該盡力使您的錯誤訊息儘可能提供資訊。好的錯誤訊息應該包含三個部分：它們應該說明錯誤是什麼，產生錯誤時軟體的狀態是什麼，以及如何修復錯誤或在哪裡找到與修復錯誤相關的資訊。

透過顯示出現了什麼問題並提出修復方法，您的使用者將花費更少的時間進行除錯並花更多時間進行科學研究。由於您比其他任何人都更瞭解您的軟體，因此在錯誤訊息中提供指導非常寶貴。如果沒有其他原因，那麼為了避免為使用者提供技術支援（大多數人幾乎沒有閱讀過您的文件，如果有的話），他們遇到了容易修復的使用錯誤。

此外，重要的是要說明生成錯誤時軟體的狀態，特別是如果執行需要很長時間或預設情況下不儲存日誌。如果您的軟體失敗，看似隨機，在執行12小時後，您的使用者將會感謝知道錯誤被丟擲時發生了什麼，而不是必須再等待12個小時才能在啟用日誌記錄的情況下重現錯誤。

規則10：告訴人們如何引用您的軟體
在本指南中的所有規則中，可能性是您需要的最少的規則。但是，必須要說的是，如果您釋出科學軟體，則需要包含正確提供工作歸屬所需的資訊。我建議在README中為您的出版物提供數字物件識別符號（DOI），BibTeX條目和書面參考，以及使用引文檔案格式（CFF）格式的“CITATION”檔案，這是一種人類和機器可讀的檔案格式，用於指定科學軟體的引用資訊。

在您的文件中包含引文資訊對於尚未在傳統學術期刊上發表的軟體尤其重要，因為該期刊會為其分配DOI。僅僅因為您的軟體未釋出並不意味著您無法獲得DOI - 您的工作值得信賴。如果您使用Zenodo存檔您的版本（參見規則6），它將為每個版本以及整個專案的DOI製作新的DOI。為您的專案獲取DOI的另一個好的，

免費的方法是將其提交給開源軟體期刊（joss.theoj.org），這是一個為軟體開發人員設計的同行評審的開放式學術期刊。兩者都為您的自述檔案提供徽章（參見規則4），以便整個世界可以一目瞭然地告訴您如何引用您的軟體。