init commit

ee0703 · Dec 5, 2015 · fe5d14a · fe5d14a
1 parent 7d19ccd
commit fe5d14a
Show file tree

Hide file tree

Showing 25 changed files with 2,127 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,3 @@
+_book/
+*.DS_Store
+node_modules/
diff --git a/README.md b/README.md
@@ -0,0 +1,23 @@
+# Python 代码规范
+
+> 代码是写给人看的, 顺带能在计算机上运行  
+>
+> -- <cite>《SICP》</cite>
+
+为了提高代码质量，便于自动测试和部署，我们急需一个统一的、通用的Python代码规范。
+本代码规范基于[PEP8](https://www.python.org/dev/peps/pep-0008/), 在PEP8的基础上做了一些改动。
+
+## 目的
+提供一个通用的，现成的规范，对大部分人来说，本规范应该是拿来就能直接用的。在写Python代码规范时，发现现成且开源的中文资源不多，所以我决定自己整理一个，作为大家制定python代码规范的参考，也可以直接拿来用。
+
+## 参与项目
+本书还需要不断完善和编辑，欢迎直接评论或者发起issu，也欢迎pull requests。
+
+## 待完成
+- [ ] 翻译awesome-python
+- [ ] pylint
+- [ ] virtualenv
+
+
+## License
+Creative Commons — CC0 1.0 Universal
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -0,0 +1,22 @@
+# Summary
+* [Python代码规范](style-guide/README.md)
+    * [简明概述](style-guide/overview.md)
+    * [注释和文档](style-guide/comment_and_docs.md)
+    * [命名规范](style-guide/variables.md)
+    * [程序设计规范](style-guide/code.md)
+* [单元测试规范](test-pattern/README.md)
+    * [单元测试简介](test-pattern/intro.md)
+    * [单元测试规范](test-pattern/pattern.md)
+    * [单元测试框架种类及样例](test-pattern/example.md)
+* [项目规范](project-guide/README.md)
+    * [包和依赖](project-guide/package.md)
+    * [静态文件](project-guide/static.md)
+    * [配置文件和数据](project-guide/config-and-data.md)
+    * [项目目录结构示例](project-guide/dir.md)
+* [优雅之道](pythonic/README.md)
+    * [Python的哲学](pythonic/zen.md)
+    * [DRY--不要重复你自己](pythonic/DRY.md)
+    * [KISS--keep it simple & small](pythonic/KISS.md)
+    * [虚拟环境--virtualenv](pythonic/virtualenv.md)
+    * [Lint工具--pylint](pythonic/lint.md)
+    * [好用的轮子](pythonic/awesome-python.md)
diff --git a/book.json b/book.json
@@ -0,0 +1,12 @@
+{
+    "plugins": [
+        "duoshuo",
+        "todo"
+    ],
+    "pluginsConfig": {
+        "duoshuo": {
+            "short_name": "pqx",
+            "theme": "default"
+        }
+    }
+}
diff --git a/project-guide/README.md b/project-guide/README.md
@@ -0,0 +1,3 @@
+# 项目规范
+
+关于python项目（尤其是web项目）的规范
diff --git a/project-guide/config-and-data.md b/project-guide/config-and-data.md
@@ -0,0 +1,11 @@
+# 配置文件和数据
+
+
+1. 如框架无特殊规定，配置文件应放置于**项目根目录下的```config```文件夹中**
+
+2. 配置文件在部署、预发布、生产环境、开发环境等环境中会有很大差异，因此请**不要将配置文件在上传到git、svn等版本库中**，
+而是建议在版本库中上传一个配置的**示例文件**（如：config.example）
+
+3. 上传到版本库中配置示例文件**不允许出现密码、证书、token等敏感信息**
+
+4. 数据和程序应该尽量分离，不要将数据写在代码中，需要持久化存储数据必须使用数据库
diff --git a/project-guide/dir.md b/project-guide/dir.md
@@ -0,0 +1,25 @@
+# 项目目录结构示例
+
+以下是一个web项目的目录结构示例
+
+```
+.project_root/                      项目根目录         
+|
+├── app/                            app代码等(不限定，可根据实际情况命名和确定结构)
+│   ├── .../
+│   ├── .../
+│   └── ...
+├── config/                         配置文件夹
+│   ├── config.ini                  配置文件（应该被版本库ignore掉）
+│   └── config.ini.example          配置文件示例
+├── static/                         静态文件夹
+│   ├── css/                        
+│   ├── img/
+│   ├── js/
+│   └── favicon.ico                 网站图标
+├── README.md                       项目说明文件
+├── requrements.txt                 项目依赖文件
+├── TODO.md                         待完成项目
+└── .gitignore                      版本库ignore文件
+
+```
diff --git a/project-guide/package.md b/project-guide/package.md
@@ -0,0 +1,24 @@
+# 包和依赖
+
+1. 如无特殊情况，项目的包管理器**一律使用pip**
+
+2. 项目**根目录下必须包含requirements.txt文件**，作为项目依赖的显示声明文件
+
+3. 所有依赖都必须显示声明，禁止隐式依赖，例如：
+
+    ```python
+    # 错误，依赖的wget在别的系统环境下很可能不存在
+    def download(url):
+        os.system('wget %s' % url)
+    ```
+    以上代码隐式依赖了wget，但很有可能开发环境中有wget，而在部署环境下根本不存在，
+    这样部署app时就很可能出错！
+
+4. 依赖声明文件中不应该包含项目中没有用到的依赖
+
+5. 建议在开发项目时使用virtualenv做依赖隔离，便于使用pip freeze自动生成
+
+    ```sh
+    # 自动生成requirement.txt示例
+    $ pip freeze > requirements.txt
+    ```
diff --git a/project-guide/static.md b/project-guide/static.md
@@ -0,0 +1,43 @@
+# 静态文件
+
+> 如无特殊说明，本文中的静态文件是指web项目中的图片、css、js等静态资源而言（有cdn的需求）
+
+
+1. 为了便于部署时使用cdn加速，静态文件应该统一存放于项目根目录下的```static```文件夹中
+
+2. 为了便于统一管理，favicon.ico文件也应该放置于static文件夹中， 在html中使用link方式引用
+
+    ```html
+    <!DOCTYPE html>
+    <html>
+    <head>
+    <title>标题</title>
+    <link rel="shortcut icon" href="http://www.xxx.com/图标的地址.../favicon.ico">
+    </head>
+    ... ...
+    ```
+
+3. 引用静态文件时，**不要用绝对路径**，可以使用django的static模板标签，或flask的url_for自动生成
+
+    * django 静态文件引用示例
+
+    ```html
+    {% raw %}
+    {% load staticfiles %}
+    <img src="{% static "my_app/myexample.jpg" %}" alt="My image"/>
+    {% endraw %}
+    ```
+
+    * flask 静态文件引用示例
+
+    ```html
+    {% raw %}
+    <img src="{% url_for "my_app/myexample.jpg" %}" alt="My image"/>
+    {% endraw %}
+    ```
+
+    * 错误的静态文件引用方式
+
+    ```html
+    <img src="/static/img/pic1.jpg" alt="My image"/>
+    ```
diff --git a/pythonic/DRY.md b/pythonic/DRY.md
@@ -0,0 +1,11 @@
+# DRY原则 -- 不要重复你自己
+
+Don't repeat yourself（不要重复你自己，简称DRY）是面向对象编程中的基本原则，程序员的行事准则。
+旨在软件开发中，减少重复的信息。
+
+DRY的原则是──系统中的每一部分，都必须有一个单一的、明确的、权威的代表──指的是（由人编写而非机器生成的）代码和测试所构成的系统，必须能够表达所应表达的内容，但是不能含有任何重复代码。
+当DRY原则被成功应用时，一个系统中任何单个元素的修改都不需要与其逻辑无关的其他元素发生改变。此外，与之逻辑上相关的其他元素的变化均为可预见的、均匀的，并如此保持同步。
+
+但过度的强调DRY，以及过早优化都是不对的，我们应该尽量避免过度抽象.有时候一定程度的冗余反而是好事.
+
+关于抽象的原则，可以参看阮一峰的[这篇文章](http://www.ruanyifeng.com/blog/2013/01/abstraction_principles.html)
diff --git a/pythonic/KISS.md b/pythonic/KISS.md
@@ -0,0 +1,12 @@
+# KISS -- keep it simple & small
+
+KISS原则是英语keep it simple & small, 或Keep It Simple, Stupid 的首字母缩略字。KISS原则是指在设计当中应当注重简约的原则。
+
+KISS原则在设计上可能最被推崇的，在家装设计，界面设计，操作设计上，复杂的东西越来越被众人所BS了，而简单的东西越来越被人所认可，比如这些UI的设计和我们中国网页（尤其是新浪的网页）者是负面的例子。
+“宜家”（IKEA）简约、效率的家居设计、生产思路；“微软”（Microsoft）“所见即所得”的理念；“谷歌”（Google)简约、直接的商业风格，无一例外的遵循了“kiss”原则，也正是“kiss”原则，成就了这些看似神奇的商业经典。而苹果公司的iPhone/iPad将这个原则实践到了极至。
+
+把一个事情搞复杂是一件简单的事，但要把一个复杂的事变简单，这是一件复杂的事。
+
+简单的东西往往更容易维护，更加稳定，也更加容易做好，这也是Unix的设计哲学（Less is more）：各模块只做好自己该做的事情.
+
+在软件设计的时候，我们也需要想清楚，某些东西是否真的需要， 也许[You aren't gonna need it](https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it).
diff --git a/pythonic/README.md b/pythonic/README.md
@@ -0,0 +1,10 @@
+# 优雅之道
+
+> 关于工具，一个最重要的，也是最不易察觉的方面是，工具对使用此工具的人的习惯的潜移默化的影响。
+> 如果这个工具是一门程序语言，不管我们是否喜欢它，它都会影响我们的思维惯式。
+>
+> -- <cite>Edsger Dijkstra</cite>
+
+Python是一门优雅的语言，使用Python就意味着要用Python的思维方式。
+实际上，很多人还用c语言的思维写Python, 这样写出来的代码读起来很费劲，而且效率也不高。
+为了提高效率，本章介绍了一些python的设计哲学、设计原则、高效率的工具和轮子等。
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# 项目规范

		关于python项目（尤其是web项目）的规范