文章目录

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

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

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

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

如何成为现代科学家:代码相关推荐

隐私合规:收集SDK部分介绍
com.meizu.cloud.pushsdk.SystemReceiver 魅族推送服务是由魅族公司为开发者提供的消息推送服务,开发者可以向集成了魅族 push SDK 的客户端实时地推送通知或者消 ...
独家 | 数据科学家对可复用Python代码的实用管理方法（附链接）
作者:Matthew Mayo, KDnuggets翻译:殷之涵校对:欧阳锦本文约3000字,建议阅读5分钟本文为大家介绍了四种关于复用Python代码的管理方法,以提高代码的效率及可读性等. 标签: ...
独家 | 如何用简单的Python为数据科学家编写Web应用程序？（附代码链接）
作者:拉胡尔·阿加瓦尔(Rahul Agarwal), Walmart 实验室的数据科学家翻译:陈之炎校对:闫晓雨本文约4300字,建议阅读10分钟. 本文阐述如何使用StreamLit创建支持 ...
你不会编程，不是你不行，很有可能是老师教的方法不好。科学家发现：对大脑而言，代码编程与语言学习不同...
点击上面"脑机接口社区"关注我们更多技术干货第一时间送达神经科学家发现解释计算机代码可以激活通用的大脑网络,但不能激活语言处理中心. 在某些方面,学习计算机编程语言与学习一门新 ...
dijkstra算法代码_数据科学家需要知道的5种图算法（附代码）
在本文中,我将讨论一些你应该知道的最重要的图算法,以及如何使用Python实现它们. 作者:AI公园导读因为图分析是数据科学家的未来. 作为数据科学家,我们对pandas.SQL或任何其他关系数据 ...
vscode查看历史代码_VSCode中数据科学家的四大代码查看器
vscode查看历史代码动机 (Motivation) Data science field requires working with data and files in different fo ...
浪漫主义计算机科学家的真知灼见——《代码整洁之道》
熟悉我的人都知道我每次写文章都要敬从当涂太白墓请来的李白三杯酒,很多人问我为什么写文章之前不拜韩愈或者苏轼反而拜成就在诗不在文的李白呢?我每次都要解释:李白是捞月的诗人,Monkey是捞月的动物,李白 ...
【阿里聚安全·安全周刊】科学家警告外星恶意代码|新方法任意解锁iPhone
本周的七个关键词: 外星恶意代码丨任意解锁iPhone 丨安卓9.0 丨黑客攻击医疗设备丨仙女座僵尸网络丨苹果联合创始人被骗比特币丨JavaScript -1- [恶意代码] ...
如何用简单的Python为数据科学家编写Web应用程序？（附代码链接）
作者:拉胡尔·阿加瓦尔(Rahul Agarwal), Walmart 实验室的数据科学家翻译:陈之炎校对:闫晓雨本文约4300字,建议阅读10分钟. 本文阐述如何使用StreamLit创建支 ...

如何成为现代科学家:代码