How to Start a Project

这是一份关于如何开始构建一个大规模开源项目的指导。内容包括了开始构建一个大型项目所需要的工具和工作流。目的是希望没有大型项目开发经验的同学可以快速开始自己的项目，并且将主要精力投入于实际的代码中。

Contents:

绪论

致所有扬帆起航的人们

勇踏前人未至之境。

To boldly go where no man has gone before.

perface

工具篇

工欲善其事，必先利其器。

Sharp tools make good work.

开发环境

Linux

Linux是一个自由的，免费的，源码开放的操作系统。也是开源软件中最著名的例子。其最主要的目的就是为了建立不受任何商品化软件版权制约的，全世界都能使用的类Unix兼容产品。而我们将服务器部署在Linux将会更加的稳定、安全、高效以及出色的性能这是windows无法比的。

Linux

关于如何选择 Linux 发行版 ： 我的建议是选用 Ubuntu 16.04

入门资料 ： 鸟哥的Linux私房菜

Shell 入门课程： Linux 命令行基础

接下来的所有具体内容，如没有特别说明，都是将基于 Ubuntu 的。当然并不影响 Mac OS 和 Windows 下的开发者阅读这份指南。

Editor or IDE

市面上 Editor 和 IDE 种类之多，让一些朋友无法选择。而对这些 Editor 和 IDE 的选择本身是一个很主观的事情，每个人都有自己的喜好和见解。最好的方法当然是自己去尝试，直到找到自己喜欢的那个，但是我这里还是相对公正的给出我心中最理想的选择。

Vim

Vim 是一个历史悠久的文本编辑器，采用模式编辑的理念，即它提供了多种模式，按键在不同的模式下作用不同。你可以在 普通模式 下浏览文件，在 插入模式 下插入文本，在 可视模式 下选择行，在 命令模式 下执行命令等等。起初这听起来可能很复杂，但是这有一个很大的优点：不需要通过同时按住多个键来完成操作，大多数时候你只需要依次按下这些按键即可。越常用的操作，所需要的按键数量越少。

因为 Vim 是直接在 Shell 中进行操作，所以我们可以将 Vim 用作远程服务器端临时调整代码所用的编辑器。鉴于 Vim 的强大扩展性，可定制性和性能，Vim当然也可以作为主力环境的一种选择。

推荐两个入门的资料:

vim-galore

简明 VIM 练级攻略

VS Code / Atom / Sublime Text

以上三者为现在比较主流的代码编辑器了，三者也常常被拿在一起作比较。其实如果允许的话，三者都可以试一试，最终找到自己最喜欢的就好。三者都非常适合当做主力的开发环境，通过各种插件的自由配置，你可以搭建一个个性化的开发环境。当然如果你就得有必要，也可以开发自己的插件。

本系列指南就是在 VS Code 下编写完成。

三者性能分析的文章 ： Sublime Text vs Visual Studio Code vs Atom Performance Test (Dec 2016)

Tips: 三者都是全平台支持。Sublime Text 目前是收费的（提供无限时长的试用），另外两个均为 Github 上开源项目。

推荐材料

Udacity Free Course : Linux 命令行基础

鸟哥的Linux私房菜 : http://linux.vbird.org/

Vim Galore : https://github.com/wsdjeg/vim-galore-zh_cn

简明 VIM 练级攻略 ： https://coolshell.cn/articles/5426.html

版本控制

关于版本控制

什么是“版本控制”？我们为什么要关心它呢？简单来说版本控制是一种记录一个或若干文件内容变化，以便将来查阅特定版本修订情况的系统。

许多人习惯用复制整个项目目录的方式来保存不同的版本，或许还会改名加上备份时间以示区别。这么做唯一的好处就是简单。不过坏处也不少：有时候会混淆所在的工作目录，一旦弄错文件丢了数据就没法撤销恢复。

VC

Image source: http://smutch.github.io/VersionControlTutorial/


Git 等版本控制工具的诞生，让版本管理变得简单和易用。

Tips: 项目无论大小，请使用版本控制。

Git简介及入门

作为Git官方推荐书籍，Pro Git 值得Git初学者和爱好者认真阅读一遍。 接下来请移步：https://bingohuang.gitbooks.io/progit2/content/

入门： 第二章，第三章

高级话题 ： 第四章至第八章，

Github 漫步指南

GitHub 是最大的 Git 版本库托管商，是成千上万的开发者和项目能够合作进行的中心。 大部分 Git 版本库都托管在 GitHub，很多开源项目使用 GitHub 实现 Git 托管、问题追踪、代码审查以及其它事情。 所以，尽管这不是 Git 开源项目的直接部分，但如果想要专业地使用 Git，你将不可避免地与 GitHub 打交道。

这个链接是 Github 超高人气用户 Phodal Huang 写的 GitHub 漫游指南。

Tips: 如果你有一个教育邮箱，你可以获得一个 Github Student Pack。 The best developer tools, free for students.

推荐材料

Pro Git (2ed,zh) : https://github.com/bingohuang/progit2-gitbook

Udacity Free Course (en/zh) : 如何使用 Git 和 GitHub

GitHub 漫游指南 (zh) : http://github.phodal.com/

Flight rules for git (en) : https://github.com/k88hudson/git-flight-rules

单元测试

如果你听说过“测试驱动开发”（TDD：Test-Driven Development），单元测试就不陌生。单元测试是用来对一个模块、一个函数或者一个类来进行正确性检验的测试工作。

test

Image source: http://simply-the-test.blogspot.com


我们讨厌测试

如果说为什么我们的项目没有测试，以下总是我们的借口：

  1. 单元测试是什么
  2. 不知道怎么编写单元测试
  3. 项目小或者项目没有要求编写单元测试
  4. 单元测试是在浪费时间
  5. 项目赶进度，没有足够的时间编写测试

重要性

既然测试是程序员十分厌倦的一个活动。测试能给我们带来什么？了解这些是非常重要的，虽然测试不可能保证一个程序是完全正确的，但是测试却可以增强我们对程序完整的信心，测试可以让我们相信程序做了我么期望它做的事情。测试能够使我们尽早的发现程序的 bug 和不足。一个 bug 被隐藏的时间越长，修复这个 bug 的代价就越大。

当然，我们主要讨论的是单元测试。单元测试是一个方法层面上的测试，也是最细粒度的测试。用于测试一个类的每一个方法都已经满足了方法的功能要求。在开发中，对于自己开发的模块，只有在通过单元测试之后，才能提交到 Git 库中。

总结三个最主要的原因：

  1. 知道你的代码是否真的可以运行。
  2. 减少Bug带来的痛苦，帮你省下大量的时间和精力。
  3. 帮助你在集成或发布前，确保你的代码是可靠的。

如何单元测试

我们将在接下来各个语言的工作流中介绍具体的单元测试框架，一些单元测试的设计准则可参考推荐材料中的几篇文章。

Tips: 即使我们讨厌测试，也要将测试变成我们的习惯。

推荐材料

单元测试准则

Writing Great Unit Tests: Best and Worst Practices

How to write “good” unit tests?

持续集成

什么是持续集成

持续集成（Continuous Integration），也就是我们经常说的 CI，是现代软件开发技术的基础。

Martin Fowler 是这样形容和解释持续集成的：

持续集成正是针对上述一系列问题的一种软件开发实践，它倡导团队开发成员必须经常集成他们的工作，甚至每天都可能发生多次集成。而每次的集成都是通过自动化的构建来验证，包括自动编译、发布和测试，从而尽快地发现集成错误，让团队能够更快的开发内聚的软件。

CI

为什么我们需要持续集成

持续集成的核心价值在于：

  1. 降低风险，每天都可能发生多次集成，有利于及早发现软件质量问题。
  2. 自动完成，通过自动化工具可以避免开发人员投入过多精力
  3. 软件运行状态随时可看，可以增加领导和团队成员对项目的信心。
  4. 利于对未来进行把控，持续集成的信息有利于我们对未来进行更好地规划和把控。

如何进行持续测试

如果选择了需要进行持续测试，就可以有两种选择：

  1. 使用第三方提供的 CI 服务，如 Travis-CI。Travis-CI 可以为 Github 上的开源项目提供免费 CI 服务。在后面的章节中，也会提到在各个语言中如何配置 Travis-CI，从而达到自动化持续集成。在下面这个教程中，将会简单介绍 Travis-CI 的使用：

    如何简单入门使用Travis-CI持续集成

    Tips: 对于 Github 上私有仓库，Travis-CI 不提供免费服务。对于 Github 教育账号，则依然免费。

  2. 自己搭建 CI 服务器。如果 Travis-CI 不能满足你的项目需求，这时候可以自己搭建 CI 服务器来为项目提供持续集成服务。现在主流的选择是 Jenkins。如有需求，请移步官网文档处学习。

推荐材料

如何简单入门使用Travis-CI持续集成

Jenkins 文档

代码质量

为什么我们关心代码质量

我们讨论的代码质量指的是代码本身的质量，包括复杂度、重复率、代码风格等要素。

代码质量下降通常会自成因果，导致恶性循环：

  • 破窗效应：在烂代码上继续生产烂代码的心理负担小很多
  • 传染性：烂代码传递着一种不在意质量，只看业务成果的负面信息，会伤害团队的技术热情和工作氛围，导致更多烂代码出现

详细的代码质量的管理和分析可以参见美团的两篇文章。以一篇从团队开发的角度，分析控制代码质量的重要性，并给出了一些理论上的指导。第二篇详细的讲述了美团在自己的代码质量检测平台中使用的衡量标准，以量化的角度讲述什么样的代码是所谓的高质量的代码。

代码质量管控的四个阶段

代码质量管控 -- 复杂度检测

流行工具

  1. 代码静态分析工具 ： 各个语言都有很多静态分析工具，比如 Clang， pylint 等等。基本上主流的分析工具都可以作为插件安装到你的编辑器中，在开发的过程中就会给出建议和提示。这些工具是代码质量的基本保证。
  2. 在线检测平台 ： 许多在现的代码检测平台，大多数都对开源项目免费。在 Github 的 Marketplace 中，列举了一个关于代码质量检测平台的清单。

推荐阅读

代码质量管控的四个阶段

代码质量管控 -- 复杂度检测

文档管理

文档的重要

很遗憾，很多人都忽视了文档对一个项目取得成功的重要性。

科技作者 Mike Pope 曾经如此总结文档的需求：

我们需要告诉开发者，缺了文档，就等于废了项目。你不仅必须写文档，还得在其中好好解释、教导和示范。这样的话，大家都会很高兴的。这不仅关乎你的文档，也关乎你的产品！

docs

GitHub《2017 开源调查》中排名靠前的几个问题，在“文档不完整或困惑”之后，分别是“不回应”、“不屑”、“冲突”、“不明原因的拒绝”、以及“不欢迎的语言或内容”。

GitHub 在调查中强调：文档有助于营造一个包容性的社区，清楚地解释了一个项目的过程，比如贡献指南和行为准则，大家会很珍视这样的开源工作、但它往往被低估。

调查还指出，高达 60% 的贡献者很少或从未对文档提供过帮助。

如何编写文档

  1. README文档。可参考 Udacity 免费课程： 编写 README 文档
  2. API文档。主流的文档工具一般有，Sphinx, doxygen 等等。我们将会在后面的章节详细介绍这些工具的使用。
  3. 托管网站。Read the Docs 可以为开源项目托管文档。

推荐阅读

Udacity Free Course (en/zh) : 编写 README 文档

语言篇

我们的语言跟我们的文化一样混乱。 —— 降临

Our language, like our culture, is messy. —— Arrival

Python

项目结构

https://github.com/Shenggan/Example-Python

代码风格

http://zh-google-styleguide.readthedocs.io/en/latest/google-python-styleguide/contents/

最佳实践

http://pythonguidecn.readthedocs.io/zh/latest/ https://github.com/vinta/awesome-python

推荐资料

https://github.com/justjavac/free-programming-books-zh_CN#python

C++

项目结构

代码风格

最佳实践

推荐资料

鸣谢