optimize PSR-1

hfcorriez · Mar 8, 2014 · 7000bd3 · 7000bd3
1 parent 6fdd709
commit 7000bd3
Showing 1 changed file with 39 additions and 39 deletions.
diff --git a/接受/PSR-1-basic-coding-standard.md b/接受/PSR-1-basic-coding-standard.md
@@ -1,131 +1,131 @@
 基本代码规范
 =====================
 
-本节标准包含了成为标准代码所需要的基本元素，以确保开源出来的PHP代码之间有较高度的技术互用性。
+本节我们将会讨论一些基本的代码规范问题，以此作为将来讨论更高级别的代码分享和技术互用的基础。
 
-在 [RFC 2119][]中的特性关键词"必须"(MUST)，“不可”(MUST NOT)，“必要”(REQUIRED)，“将会”(SHALL)，“不会”(SHALL NOT)，“应当”(SHOULD)，“不应”(SHOULD NOT)，“推荐”(RECOMMENDED)，“可以”(MAY)和“可选”(OPTIONAL)在这文档中将被用来描述。
+[RFC 2119][]中的`必须(MUST)`，`不可(MUST NOT)`，`建议(SHOULD)`，`不建议(SHOULD NOT)`，`可以/可能(MAY)`等关键词将在本节用来做一些解释性的描述。
 
 [RFC 2119]: http://www.ietf.org/rfc/rfc2119.txt
 [PSR-0]: https://github.com/hfcorriez/fig-standards/blob/zh_CN/接受/PSR-0.md
 
 
-1. 大纲
+1. 概述
 -----------
 
-- 源文件`必须`只使用 `<?php` 和 `<?=` 标签。
+- 源文件`必须`只使用 `<?php` 和 `<?=` 这两种标签。
 
-- 源文件中`必须`只使用不带BOM的UTF-8作为PHP代码。
+- 源文件中php代码的编码格式`必须`只使用不带`字节顺序标记(BOM)`的`UTF-8`。
 
-- 源文件`应当`只声明符号（类，函数，常量等...）或者引起副作用（例如：生成输出，修改.ini配置等）,但`不应`同时做这两件事。
+- 一个源文件`建议`只用来做声明（`类(class)`，`函数(function)`，`常量(constant)`等）或者只用来做一些引起副作用的操作（例如：输出信息，修改`.ini`配置等）,但`不建议`同时做这两件事。
 
-- 命名空间和类`必须`遵守 [PSR-0][]。
+- `命名空间(namespace)`和`类(class)` `必须`遵守[PSR-0][]标准。
 
-- 类名`必须`使用骆驼式`StudlyCaps`写法 (译者注：驼峰式的一种变种，后文将直接用`StudlyCaps`表示)。
+- `类名(class name)` `必须`使用`骆驼式(StudlyCaps)`写法 (译者注：`驼峰式(cameCase)`的一种变种，后文将直接用`StudlyCaps`表示)。
 
-- 类中的常量`必须`使用全大写和下划线分隔符。
+- `类(class)`中的常量`必须`只由大写字母和`下划线(_)`组成。
 
-- 方法名`必须`使用驼峰式`cameCase`写法(译者注：后文将直接用`camelCase`表示)。
+- `方法名(method name)` `必须`使用`驼峰式(cameCase)`写法(译者注：后文将直接用`camelCase`表示)。
 
 
 2. 文件
 --------
 
 ### 2.1. PHP标签
 
-PHP代码`必须`只使用长标签`<?php ?>`或者短输出式`<?= ?>`标签；它`不可`使用其他的标签变种。
+PHP代码`必须`只使用`长标签(<?php ?>)`或者`短输出式标签(<?= ?>)`；而`不可`使用其他标签。
 
 ### 2.2. 字符编码
 
-PHP代码`必须`只使用不带BOM的UTF-8。
+PHP代码的编码格式`必须`只使用不带`字节顺序标记(BOM)`的`UTF-8`。
 
 ### 2.3. 副作用
 
-一个文件`应当`声明新符号 (类名，函数名，常量等)并且不产生副作用，或者`应当`执行有副作用的逻辑，但不能同时做这两件事。
+一个源文件`建议`只用来做声明（`类(class)`，`函数(function)`，`常量(constant)`等）或者只用来做一些引起副作用的操作（例如：输出信息，修改`.ini`配置等）,但`不建议`同时做这两件事。
 
-短语"副作用"意思是不直接执行逻辑的类，函数，常量等 *仅包括文件*
+短语`副作用(side effects)`的意思是 *在包含文件时* 所执行的逻辑与所声明的`类(class)`，`函数(function)`，`常量(constant)`等没有直接的关系。
 
-“副作用”包含但不局限于：生成输出，显式地使用`require`或`include`，连接外部服务，修改ini配置，触发错误或异常，修改全局或者静态变量，读取或修改文件等等
+`副作用(side effects)`包含但不局限于：产生输出，显式地使用`require`或`include`，连接外部服务，修改ini配置，触发错误或异常，修改全局或者静态变量，读取或修改文件等等
 
 下面是一个既包含声明又有副作用的示例文件；即应避免的例子：
 
 ```php
 <?php
-// side effect: change ini settings
+// 副作用：修改了ini配置
 ini_set('error_reporting', E_ALL);
 
-// side effect: loads a file
+// 副作用：载入了文件
 include "file.php";
 
-// side effect: generates output
+// 副作用：产生了输出
 echo "<html>\n";
 
-// declaration
+// 声明
 function foo()
 {
-    // function body
+    // 函数体
 }
 ```
 
-下面是一个仅包含声明的示例文件；即需要提倡的例子：
+下面是一个仅包含声明的示例文件；即应提倡的例子：
 
 ```php
 <?php
-// declaration
+// 声明
 function foo()
 {
-    // function body
+    // 函数体
 }
 
-// conditional declaration is *not* a side effect
+// 条件式声明不算做是副作用
 if (! function_exists('bar')) {
     function bar()
     {
-        // function body
+        // 函数体
     }
 }
 ```
 
 
-3. 命名空间和类名
+3. `空间名(namespace)`和`类名(class name)`
 ----------------------------
 
-命名空间和类名必须遵守 [PSR-0][].
+`命名空间(namespace)`和`类(class)`必须遵守 [PSR-0][].
 
-这意味着每个类必须单独一个源文件，并且至少有一级命名空间：顶级的组织名。
+这意味着一个源文件中只能有一个`类(class)`，并且每个`类(class)`至少要有一级`空间名（namespace）`：即一个顶级的`组织名(vendor name)`。
 
-类名必须使用骆驼式`StudlyCaps`写法。
+`类名(class name)` `必须`使用`StudlyCaps`写法。
 
-PHP5.3之后的代码`必须`使用正式的命名空间
+`PHP5.3`之后的代码`必须`使用正式的`命名空间(namespace)`
 例子：
 
 ```php
 <?php
-// PHP 5.3 and later:
+// PHP 5.3 及之后:
 namespace Vendor\Model;
 
 class Foo
 {
 }
 ```
 
-PHP5.2.x之前的代码应当用伪命名空间`Vendor_`作为类名的前缀
+`PHP5.2.x`之前的代码`建议`用伪命名空间`Vendor_`作为`类名(class name)`的前缀
 
 ```php
 <?php
-// PHP 5.2.x and earlier:
+// PHP 5.2.x 及之前:
 class Vendor_Model_Foo
 {
 }
 ```
 
-4. 类常量，属性和方法
+4. 类的常量、属性和方法
 -------------------------------------------
 
-术语“类”指所有的类，接口和特性(traits)
+术语`类(class)`指所有的`类(class)`，`接口(interface)`和`特性(trait)`
 
 ### 4.1. 常量
 
-类常量`必须`使用全大写，并使用分隔符作为下划线。
+类常量`必须`只由大写字母和`下划线(_)`组成。
 例子：
 
 ```php
@@ -141,10 +141,10 @@ class Foo
 
 ### 4.2. 属性
 
-本手册有意避免推荐使用`$StulyCaps`，`$camelCase`或者`unser_score`作为属性名字
+本指南中故意不对`$StulyCaps`，`$camelCase`或者`$unser_score`中的某一种风格作特别推荐，完全由读者依据个人喜好决定属性名的命名风格。
 
-不管名称如何约定，它`应当`在一个合理范围内保持一致。这个范围可能是组织层，包层，类层，方法层。
+但是不管你如何定义属性名，`建议`在一个合理的范围内保持一致。这个范围可能是`组织(vendor)`级别的，`包(package)`级别的，`类(class)`级别的，或者`方法(method)`级别的。
 
 ### 4.3. 方法
 
-方法名必须用`camelCase()`写法。
+方法名则`必须`使用`camelCase()`风格来声明。