文章目录

• 1. Scientific code - what should I do and why?
• • 1.1 Post your code to a public repository
  • 1.2 Organize and document your code
  • 1.3 Include links to your code in your publications
  • 1.4 When sharing software, use repositories with review
• 2. Scientific code - what tools should I use?
• • 2.1 Posting general code
  • 2.2 Posting software
  • 2.3 Posting analysis code
  • • 2.3.1 Code and scripts
    • 2.3.2 Literate programming
• 3. Scientific code - further tips and issues
• • 3.1 Analysis code
  • • 3.1.1 Commenting and documenting
    • 3.1.2 Reporting versions
    • 3.1.3 Session information
  • 3.2 Software packages
  • • 3.2.1 Naming your software
    • 3.2.2 Versioning your software
  • 3.3 Documentation
  • • 3.3.1 Help files
    • 3.3.2 Vignettes
  • 3.4 Good writers borrow from other authors, great authors steal

1. Scientific code - what should I do and why?

  代码和数据类似，都应该被开源，这是由于代码包含了论文中的分析过程。

1.1 Post your code to a public repository

  最好把数据提交到公开的仓库中，如通用代码服务网站github。否则更改网站、管理数据就会变得非常麻烦。

1.2 Organize and document your code

  在线上传代码是很简单的，但是通常来说代码会被完全随意的存放。

  原因很简单，根据历史数据统计，很少人会经过深思熟虑然后以具有规范性的方式来上传代码。

  为了最大化数据的价值，最好做到以下三点：(a) 将代码上传到开源仓库 (b) 标注所使用库的版本 (c) 使用README文件，利用注释和文学编程(literate programming)来记录和解释您的代码。

1.3 Include links to your code in your publications

  令人惊讶的是，即使公开发布了论文的相关代码，也常常难以发现。所以最好在论文或者别的出版物中直接附上链接。

1.4 When sharing software, use repositories with review

  通过Github发布Python或者R的包非常容易。但上传的代码却并没有经过审核。如果把代码上传到具有审核能力的库（如CRAN或者Bioconductor），就会大大提高代码的可靠性和实用性。

2. Scientific code - what tools should I use?

2.1 Posting general code

  要发布通用性的代码，请使用具有共享性和版本控制的系统。最常用的两个是Github和Bitbucket。不要使用非版本控制系统，如Dropbox来分享代码。

2.2 Posting software

• R，可发布在通用性软件库CRAN或者rOpenSci，如果是生物类软件，可以发布在Bioconductor。
• Python，可发布在PyPI上(https://pypi.python.org/pypi)。

2.3 Posting analysis code

  共享代码有两种主要的方法：共享代码文件和文学编程文档。

2.3.1 Code and scripts

  最基本的方法是通过代码文件来共享代码。最好在编写和发布代码时使用版本控制软件。

2.3.2 Literate programming

  文学编程文档是把代码和文本融合到文档之中，从而方便在文档中进行解释。在R语言中，最常用的文学编程工具是knitr和rmarkdown。在其他语言中最常用的是Jupyter Notebook。文学编程的优点是可以进行高效的解释分析过程。

3. Scientific code - further tips and issues

3.1 Analysis code

3.1.1 Commenting and documenting

  在文本形式的代码文件中，最好是使用注释来描述代码的作用。在文学编程文档中，例如R markdown或者Jupyter Notebook，可以使用自然语言来描述代码。注释中最好包括以下内容：(a) 为什么要完成这个代码 (b)代码的基本原理 (c)输入和输出分别是什么。

3.1.2 Reporting versions

  当编写分析文档和发布出版物时，应当写下软件所使用的版本号。

3.1.3 Session information

  分析代码应当包括可以输出硬件、软件平台、软件包所有版本号的命令。即使后续软件版本发生变化，人们也可以根据自己的实际情况进行调整。

3.2 Software packages

3.2.1 Naming your software

  创建软件的第一步是对软件进行命名。以下是Hadley Wickham起名的一些建议：

• 可以通过谷歌搜索到。
• 确保在该软件库中不和其它软件重名。
• 没有下划线、破折号和其他特殊符号。
• 名称全部使用小写字母。
• 令人容易记住，但不要使用太俏皮的名字。
• 名称不要太长，否则不便于记忆和检索。

3.2.2 Versioning your software

  使用版本控制来进行软件开发，存在着很多潜在的约定。其中一个比较有用的是，考虑软件的开发和发行版本。发行版本是每个人在使用的稳定版本，而开发版是进行实验性更改的版本。

  比较常用的版本号命名方式为 x.y.z。当开启新的软件开发时，版本号应该为0.1.0。每次公开发布修改时（例如推送到Github上），都应当在版本号z上加1。但是如果只是进行本地提交但没有推送到网上时，不需要对版本号z进行修改。

  如果对整个系统架构或者使用方式进行了重新设计，就可以对版本号y进行增加。

  首次正式发布的时候，应当把版本号设置为1.0.0。正式发布后，如果打算继续从事该项目，则应将开发版本提高到1.1.0。

  因此，此后进行公共发布修改时，对版本号z进行添加。如果是进行重大重构，则对版本号y进行添加。

3.3 Documentation

  这是我对软件开发中各个部分重要程度的看法：文档>可用性>速度>统计优势。

  在理想情况下，软件是可以正常使用而且容易理解的。但我们并不是大公司（例如苹果），所以并没有太多的测试人员进行测试。所以，软件的前几个版本可能不是很好用。最初版本的性能可能会比期望的要慢。

  但如果软件解决了现实中的问题，并且具有很好的文档，人们就会去使用它，并且会在一定程度上对世界造成好的影响。

  文档应当是由两部分组成的：第一部分是帮助文件，第二部分是小插图或者教程。

3.3.1 Help files

  文档应当清晰地说明了对用户的API接口，包括函数、方法、类等。具体来说，文档应当记录了(a)所有函数的输入(b)所有函数的输出(c)一般情况下，函数实现的功能。应当举例说明如何使用API接口。

3.3.2 Vignettes

  帮助文件非常重要，但是同样重要的是帮助人们入门。方便人们入门可以使用小插图的方式。小插图是一种教程，包括了以下的几个部分：

• 简短的说明，包括可使用的数据类型和软件的主要功能。
• 示例分析，包括以下几个部分：
    - 小型真实数据集
    - 对关键功能的说明
    - 对上述数据集的实际操作说明
    - 输出结果说明

  小插图是软件被广泛使用的重要组成部分。会让人们在起床后运行你的软件，并且作为他们工作的起点。任何受欢迎的软件都应该包括小插图或者教程。

3.4 Good writers borrow from other authors, great authors steal

  我认为很多学者（包括我自己）都在努力创造具有创新性的事物。所以在学术界可能会有很大的压力。

  但是在编写软件时，非常重要的是不要重复造轮子。在编写通用性函数之前，最好搜索一下是否已经有别人写好的。

  一个重要的原则是，尽量减少软件的依赖关系。判断软件可靠程度的方法是查看软件的下载数/用户数、检查软件是否正在积极更新（最好是用更新的历史记录，看看作者是否定期更新维护软件）。

本文来自互联网用户投稿，文章观点仅代表作者本人，不代表本站立场，不承担相关法律责任。如若转载，请注明出处。 如若内容造成侵权/违法违规/事实不符，请点击【内容举报】进行投诉反馈！