原文出处： koala bear

本人打仗过数个 Open Source 项目，如 OpenStack／Kubernetes 等，深感这些优秀的开源项目存在着一些共性，如：雅观的代码，完整的测试，设计理念，框架和架构等等。一般来说，遵循这些优良原则的项目在易读性，可维护性，出格是（成果和局限的）可扩展性会更强些。

本文探讨性的梳理部门开源项目某些配合的优秀之处，可是软件工程规模，差异业务／语言的项目千差万别，故“尺度”二字也是相对的，更适合于 golang/python 语言编写的 LAM（Linux／Apache／Mysql）后端项目，争议之处请多包容。

目次组织与定名

目次组织

差异语言下的目次组织大概会有很大的差别，可是都遵循以下共鸣：

语义贴切：文件／目次的定名要尽大概表达其成果／用途

集华夏则：成果临近的文件／目次应会合存放

譬喻：

your_project /
|-- contrib /        # 存放一些如 rpm.spec，剧本等等
|-- doc /            # 文档相关
|-- examples /       # 样例说明
|-- etc(or conf) /   # 设置文件
|-- src /
    |-- api /               # api 相关代码
    |-- cmd(or cli) /       # command 相关代码，
    |-- db /                # database 相关代码
    |-- rpc /               # rpc 相关代码
    |-- tests /             # 测试文件目次
    |-- utils(or common) /  # 一些民众的要领
    |-- ...                 # 其它目次/文件
|-- README           # 项目说明
|-- .gitigore        # 忽略的 git 文件和目次
|-- ...              # 其它目次／文件

api：存放 api 相关代码，昆山软件开发，好比 route，filter，middleware，serialize/de-serialize 等。

contrib：存放一些编包的文件，git 的 patch 文件，systemd 的设置文件，以及剧本等等。

db：存放 database(如：sql/NoSQL) 相关代码，包罗 model, connection, session，orm/sql。是代码层面会见 db 的独一进口，发起所有会见 database 的操纵都必需在代码层面颠末 db 目次下的代码。

utils：一般存放一些民众的要领，如 time／date，encoding／decoding，exec，regex，uuid，string／json 等等。

推荐阅读：

What is the best project structure for a Python application?

What is a sensible way to layout a Go project

定名

匈牙利定名法和 unix 定名法是常见的定名气势气魄，一般来说，c 和 python 以 unix 定名法居多，golang 和 java 以匈牙利定名法居多。编程进程中，遵循一致的定名气势气魄，会使得代码更为雅观，可读性强。

编程中贴切的缩写常见单词，可使得代码更为简捷雅观，可是缩写最好应遵循某些约定成俗，制止发生歧义。

一般环境下不发起回收拼音定名和拼音缩写。

推荐阅读：

Google Python Style Guides

Google Shell Style Guide

一个查单词缩写的网站

宣布与运行

为什么应用的宣布和运行也应该遵循必然的法则呢？首先，用户体验更好。好比，软件工程师习惯性在 /etc 寻找设置文件，/var/log 寻找日志文件。其次，遵循这些法则有利于被运维软件打点，如 ansible，chef 等等。最后，linux 及相关软件在设计时就已经遵循这些法则，假如你的应用不遵循，大概会发生某些斗嘴。

版本号

宣布版本时，版本号的定名需要遵循某种法则，个中 Semantic Versioning 2.0.0 界说了一套简朴的法则。重点如下： 版本号的名目为 X.Y.Z(又称 Major.Minor.Patch)，递增的法则为：

X 暗示主版本号，当 API 的兼容性变革时，X 需递增。

Y 暗示次版本号，当增加成果时(不影响 API 的兼容性)，Y 需递增。

Z 暗示修订号，当做 Bug 修复时(不影响 API 的兼容性)，Z 需递增。

1. X, Y, Z 必需为非负整数，且不得包括前导零，必需按数值递增，如 1.9.0 -> 1.10.0 -> 1.11.0
2. 当 API 的兼容性变革时，X 必需递增，Y 和 Z 同时配置为 0；当新增成果(不影响 API 的兼容性)可能 API 被标志为 Deprecated 时，Y 必需递增，同时 Z 配置为 0；当举办 bug fix 时，Z 必需递增。
3. 版本一经宣布，不得修改其内容，任何修改必需在新版本宣布！

推荐阅读：

Semantic Versioning 2.0.0

打包

差异语言的应用大概有差异的打包和宣布类型，如 java 的 jar 包，python 的 wheel 包，它们极大的简化了应用的安装／进级／打点等等，很是利便的办理了版本和依赖问题。可是上述的打包方法在通用性上有所欠缺，只能被特定语言的东西打点，昆山软件开发，好比 jar 包需要被 maven 等打点，wheel 包需要 pip 等打点。为此 Redhat 界说了 redhat package management(即 rpm 包)，所有语言的应用都可以建造成 rpm 包，然后用 rpm 和 yum 等常用东西举办打点。与此雷同，ubuntu 也界说了 debian 包。

小我私家认为，应用最好以软件包的形式宣布，制止直接拷贝源码可能二进制文件到线上。

推荐阅读：

How to create an RPM package

Python application 的打包和宣布

运行