完成除第 5 章外的进一步修订工作

translation/1-前言.md

@@ -1,39 +1,24 @@
 # Preface 前言
 
-We started writing this book on November 2013. The initial goal was to provide guidelines to write the most clean Objective-C code possible: there are too many guidelines out there and all of them are debatable. We didn't aim introducing hard rules but, instead, a way for writing code to be more uniform as possible across different developers.
-With time the scope moved to explain how to design and architecture good code.
-
-我们在 2013 年 11 月份开始写这本书，最初的目标是提供一份编写干净漂亮的 Objective-C 代码的指南：现在虽然有很多指南，但是它们都是有一些问题的。我们不想介绍一些死板的规定，我们想提供一个在不同开发者之间能一致的写代码的方法。随时间的推移，这本书开始转向介绍如何设计和构建优秀的代码。
-
-The idea underneath is that the code should not only compile, instead it should "validate". Good code has several characteristics: should be concise, self-explanatory, well organized, well documented, well named, well designed and stand the test of time.
-The main goals behind the curtain are that clarity always wins over performance and a rationale for a choice should always be provided.
-Some topics discussed here are general and independent from the language even if everything is tied up to Objective-C.
+我们在 2013 年 11 月份开始写这本书，最初的目标是提供一份编写干净漂亮的 Objective-C 代码的指南：现在虽然有很多指南，但是它们都是有一些问题的。我们不想介绍一些死板的规定，我们想提供一个在开发者们之间写更一致的代码的方法。随时间的推移，这本书开始转向介绍如何设计和构建优秀的代码。
 
 这本书的理念是代码不仅是可以编译的，同时应该是 “有效” 的。好的代码有一些特性：简明，自我解释，优秀的组织，良好的文档，良好的命名，优秀的设计以及经得起时间的考验。
 这本书的理念是是代码的清晰性优先于性能，同时提供为什么这么做的原因。
 虽然所有的代码都是 Objective-C 写的，但是一些主题是通用的并且独立于编程语言的。
 
 ## Swift
 
-On June 6th, 2014 Apple announced the new programming language to be used for iOS and Mac development in future: Swift.
-This new language is a radical departure from Objective-C and, of course, has caused a change in our plan for writing this book. It boiled down to the decision of releasing the current status of this essay without continuing our journey in unfolding the topics we originally planned to include.
-Objective-C is not going anywhere but at the same time continuing to write a book on a language that will not receive the same attention as it used to, is not a wise move.
-
-在2014年6月6日，苹果发布了面向 iOS 和 Mac 开发的新语言： Swift。
-这个新语言与  Objective-C 截然不同，所以，也改变了我们书写这本书的计划，我们决定发布这本书当前的状态，而不是继续书写我们原来计划写下去的主题。
+在 2014 年 6 月 6 日，苹果发布了面向 iOS 和 Mac 开发的新语言： Swift。
+这个新语言与 Objective-C 截然不同。所以，我们改变了写这本书的计划。我们决定发布这本书当前的状态，而不是继续书写我们原来计划写下去的主题。
 Objective-C 没有消失，但是现在用一个慢慢失去关注的语言来继续写这本书并不是一个明智的选择。
 
-## For the Community 关于社区
-
-We have released this book for free and for the community because we hope to provide value to the reader, if each one of you can learn at least one best practice we have reached our goal.
-
-We have done our best to polish this text and make it pleasant to the reader but we may have made typos, mistakes or left any part incomplete. We strongly encourage you to give us feedback and suggest improvements, so please get in touch with us if have any. We particularly appreciate pull requests.
+## 贡献给社区
 
 我们将这本书免费发布并且贡献给社区，因为我们希望提供给读者一些有价值的内容。如果你能学到至少一条最佳实践，我们的目的就达到了。
 
 我们已经非常用心地打磨了这些文字，但是仍然可能有一些拼写或者其他错误。我们非常希望读者给我们一个反馈或者建议，以来改善本书。所以如果有什么问题的话，请联系我们。我们非常欢迎各种 pull-request。
 
-## Authors 作者
+##  作者
 
 **Luca Bernardi**
 

translation/10-代码组织.md

@@ -1,19 +1,13 @@
+# 代码组织
 
+[来自](http://nshipster.com/pragma/) Mattt Thompson
 
+> code organization is a matter of hygiene  (代码组织是卫生问题)
 
-# Code Organization 代码组织
 
-[Quoting](http://nshipster.com/pragma/) Mattt Thompson
+我们十分赞成这句话。清晰地组织代码和规范地进行定义, 是你对自己以及其他阅读代码的人的尊重。
 
-> code organization is a matter of hygiene  代码组织是卫生问题
-
-We could not agree more. Having you code clearly organized in a clean and defined manner is a way to show respect for yourself and other people that will read and change you code (consider the future you included).
-
-我们十分赞成这句话。清晰地组织代码和规范地进行定义是你对自己以及其他看代码的人的尊重。
-
-## Exploit Code Block 利用代码块
-
-A very obscure GCC behavior that it is also supported by Clang is the ability of a code block to return the value of the latest statement if enclosing in round bracket.
+## 利用代码块
 
 一个 GCC 非常模糊的特性，以及 Clang 也有的特性是，代码块如果在闭合的圆括号内的话，会返回最后语句的值
 
@@ -25,34 +19,20 @@ NSURL *url = ({
     [NSURL URLWithString:urlString];
 });
 ```
-This feature can be nicely organized to group small chunk of code that usually are necessary only for the sole purpose of setting up a class.
-This gives a reader an important visual clue and help reduce the visual noise focusing on the most important variable in the function.
-Additionally, this technique has the advantage that all the variables declared inside the code block, as one might expect, are valid only inside that scope, this mean that the your not polluting the method's stack trace and you can reuse the variable name without having duplicated symbols.
 
-
-这个特性非常适合组织小块的代码，通常是设置一个类。他给了读者一个重要的线索并且减少干扰，能让读者聚焦于关键的变量和函数中。此外，这个技术有一个优点，所有的变量都在代码块中，也就是只在代码块的区域中有效，这意味着可以减少对其他作用域的命名污染。
+这个特性非常适合组织小块的代码，通常是设置一个类。他给了读者一个重要的入口并且减少相关干扰，能让读者聚焦于关键的变量和函数中。此外，这个方法有一个优点，所有的变量都在代码块中，也就是只在代码块的区域中有效，这意味着可以减少对其他作用域的命名污染。
 
 ## Pragma 
 
 ### Pragma Mark
 
-`#pragma mark -` is a great way to organize the code inside a class and helps you grouping methods implementation.
-We suggest to use `#pragma mark -`to separate:
-
- `#pragma mark -`  是一个在类内部组织代码并且帮助你分组方法实现的好方法。 我们建议使用  `#pragma mark -` 来分离:
-
-
-- methods in functional groupings 
-- protocols implementations.
-- methods overridden from a superclass
 
+`#pragma mark -`  是一个在类内部组织代码并且帮助你分组方法实现的好办法。 我们建议使用  `#pragma mark -` 来分离:
 
 - 不同功能组的方法 
 - protocols 的实现
 - 对父类方法的重写
 
-
-
 ```objective-c
 
 - (void)dealloc { /* ... */ }
@@ -87,36 +67,25 @@ We suggest to use `#pragma mark -`to separate:
 
 #pragma mark - ZOCSuperclass
 
-// ... overridden methods from ZOCSuperclass
+// ... 重载来自 ZOCSuperclass 的方法
 
 #pragma mark - NSObject
 
 - (NSString *)description { /* ... */ }
 
 ```
 
-The above marks will help to visually separate and organize the code. One of the pros is that you can cmd+click on the mark to jump to the symbol definition.
-Be aware that even though the use of pragma mark is a sign of craftsmanship, it's not a good reason to make grow the number of methods in your class in a unbounded fashion: having too many of them should be a warning sign that your class has too many responsibilities and a good opportunity for refactoring.
-
-
-上面的标记能显示分离和组织代码。一个优点是你可以用  cmd+Click 来快速跳转到符号定义地方。
-但是小心，即使 paragma mark 是一门手艺，但是它不是让你类里面方法数量增加的一个理由：有太多方法说明你的类做了太多事情，需要考虑重构了。
-
-### Notes about pragma 关于 pragma
 
-At http://raptureinvenice.com/pragmas-arent-just-for-marks there's a great discussion about pragmas, reported in part here.
+上面的标记能明显分离和组织代码。你还可以用  cmd+Click 来快速跳转到符号定义地方。
+但是小心，即使 paragma mark 是一门手艺，但是它不是让你类里面方法数量增加的一个理由：类里面有太多方法说明类做了太多事情，需要考虑重构了。
 
-在 http://raptureinvenice.com/pragmas-arent-just-for-marks 有很好的关于 pragma 的讨论了，【疑问】
+### 关于 pragma
 
-While most iOS developers don't play around much with compiler options, some options are useful to control how strictly to check (or not check) your code for errors. Sometimes, though, you want to make an exception directly in your code using a pragma, which purpose is to temporarily disable a compiler behavior.
+在 http://raptureinvenice.com/pragmas-arent-just-for-marks 有很好的关于 pragma 的讨论了，在这边我们再做部分说明。
 
 大多数 iOS 开发者平时并没有和很多编译器选项打交道。一些选项是对控制严格检查（或者不检查）你的代码或者错误的。有时候，你想要用 pragma 直接产生一个异常，临时打断编译器的行为。
 
-When you use ARC, the compiler inserts memory-management calls for you. There are cases, though, where it can get confused. One such case is when you use `NSSelectorFromString` to have a dynamically-named selector called. Since ARC can't know what the method will be and what kind of memory management to use, you'll be warned with `performSelector may cause a leak because its selector is unknown`.
-
-当你使用ARC的时候，编译器帮你插入了内存管理相关的调用。但是这样可能产生一些烦人的事情。比如你使用  `NSSelectorFromString`  来动态地产生一个 selector 调用的时候，ARC不知道这个方法是哪个并且不知道应该用那种内存管理方法，你会被提示 `performSelector may cause a leak because its selector is unknown`.
-
-If you know your code won't leak, you can suppress the warning for just this instance by wrapping it like this:
+当你使用ARC的时候，编译器帮你插入了内存管理相关的调用。但是这样可能产生一些烦人的事情。比如你使用  `NSSelectorFromString`  来动态地产生一个 selector 调用的时候，ARC不知道这个方法是哪个并且不知道应该用那种内存管理方法，你会被提示 `performSelector may cause a leak because its selector is unknown（执行 selector 可能导致泄漏，因为这个 selector 是未知的）`.
 
 如果你知道你的代码不会导致内存泄露，你可以通过加入这些代码忽略这些警告
 
@@ -129,19 +98,13 @@ If you know your code won't leak, you can suppress the warning for just this ins
 #pragma clang diagnostic pop
 ```
 
-Note how we disable the -Warc-performSelector-leaks check by pushing and popping the change around our code. This assures us we don't disable it globally, which would be a huge mistake.
 
 注意我们是如何在相关代码上下文中用 pragma 停用 -Warc-performSelector-leaks 检查的。这确保我们没有全局禁用。如果全局禁用，可能会导致错误。
 
-The entire list of options that can be enable or disabled can be found at [The Clang User's Manual](http://clang.llvm.org/docs/UsersManual.html) to learn about all of them.
-
 全部的选项可以在 [The Clang User's Manual](http://clang.llvm.org/docs/UsersManual.html)  找到并且学习。
 
-Suppressing warnings for unused variables
-
-忽略没用使用变量的编译警告
 
-It's useful to be told that a variable you've defined is going unused. In most cases, you want to remove these references to improve performance (however slightly), but sometimes you want to keep them. Why? Perhaps they have a future usage or the functionality is only temporarily removed. Either way, a smarter way to suppress the warning without brutally commenting out the relevant lines, is to use the `#pragma unused()`:
+### 忽略没用使用变量的编译警告
 
 这对表明你一个定义但是没有使用的变量很有用。大多数情况下，你希望移除这些引用来（稍微地）提高性能，但是有时候你希望保留它们。为什么？或许它们以后有用，或者有些特性只是暂时移除。无论如何，一个消除这些警告的好方法是用相关语句进行注解，使用 `#pragma unused()`:
 
@@ -155,13 +118,10 @@ It's useful to be told that a variable you've defined is going unused. In most c
 }
 ```
 
-Now you can keep your code in place without the compiler complaining about it. And yes, that pragma needs to go below the offending code.
+现在你的代码不用任何编译警告了。注意你的 pragma 需要标记到未定义的变量之下。
 
-现在你的代码不用任何编译警告了。而且，这个【疑问】 
+## 明确编译器警告和错误
 
-## Explicit warnings and errors 明确编译器警告和错误
-
-The compiler is a robot: it will mark what's wrong with your code using a set of rules that've been defined by Clang. But, every so often you're smarter than it. Often, you might find some offending code that you know will lead to problems but, for whatever reason, can't fix yourself at the moment. You can explicitly signal errors like this:
 
 编译器是一个机器人，它会标记你代码中被 Clang 规则定义为错误的地方。但是，你总是比 Clang 更聪明。通常，你会发现一些讨厌的代码 会导致这个问题，而且不论怎么做，你都解决不了。你可以这样明确一个错误：
 
@@ -175,8 +135,6 @@ The compiler is a robot: it will mark what's wrong with your code using a set of
 ```
 
 
-You can signal warnings similarly:
-
 类似的，你可以这样标明一个 警告
 
 
@@ -193,31 +151,23 @@ You can signal warnings similarly:
 }
 ```
 
-## Docstrings  字符串文档
+## 字符串文档
 
-All non-trivial methods, interfaces, categories, and protocol declarations should have accompanying comments describing their purpose and how they fit into the larger picture. For more examples, see the Google Style Guide around [File and Declaration Comments](http://google-styleguide.googlecode.com/svn/trunk/objcguide.xml#File_Comments).
 
 所有重要的方法，接口，分类以及协议定义应该有伴随的注释来解释它们的用途以及如何使用。更多的例子可以看 Google 代码风格指南 [File and Declaration Comments](http://google-styleguide.googlecode.com/svn/trunk/objcguide.xml#File_Comments)。
 
-To summarize: There are two types of docstrings, long-form and short-form.
-
 简而言之：有长的和短的两种字符串文档。
 
-A short-form docstring fits entirely on one line, including the comment slashes. It is used for simple functions, especially (though by no means exclusively) ones that are not part of a public API:
-
 短文档适用于单行的文件，包括注释斜杠。它适合简短的函数，特别是（但不仅仅是）非 public 的 API：
 
 ```
 // Return a user-readable form of a Frobnozz, html-escaped.
 ```
 
-Note that the text is specified as an action ("return") rather than a description ("returns").
 
-注意文本用一个动作 ("return")  而不是一个描述 ("returns") 来定义
+文本应该用一个动词 ("return")  而不是 "returns" 这样的描述。
 
-If the description spills past one line, you should move to the long-form docstring: a summary line (one physical line) preceded by an opening block comment with two asterisks on a line of its own (/\*\*, terminated by a period, question mark, or exclamation point, followed by a blank line, followed by the rest of the doc string starting at the same cursor position as the first quote of the first line, ending with an end-block comment (\*/) on a line by itself.
-
-如果描述超出一行，你应该用长的字符串文档: 一行斜杠和两个星号来开始块文档 (/\*\*, 用 一个【疑问】
+如果描述超出一行，你应该用长的字符串文档: 一行斜杠和两个星号来开始块文档 (/\*\*, 之后是总结的一句话，可以用句号、问号或者感叹号结尾，然后空一行，在和第一句话对齐写下剩下的注释，然后用一个 (\*/)来结束。
 
 ```
 /**
@@ -229,40 +179,22 @@ If the description spills past one line, you should move to the long-form docstr
 */
 ```
 
-A function must have a docstring unless it meets all of the following criteria:
-
-一个函数必须有一个字符串文档，除非它符合下面的所有条件
 
-* not externally visible
-* very short
-* obvious
+一个函数必须有一个字符串文档，除非它符合下面的所有条件：
 
 * 非公开
 * 很短
 * 显而易见
 
+字符串文档应该描述函数的调用符号和语义，而不是它如何实现。
 
-The docstring should describe the function's calling syntax and its semantics, not its implementation.
-
-字符串文档应该描述函数的调用符号和语义，而不是它的实现
-
-## Comments  注释
-
-
-When they are needed, comments should be used to explain why a particular piece of code does something. Any comments that are used must be kept up-to-date or deleted.
-
+##  注释
 
 当它需要的时候，注释应该用来解释特定的代码做了什么。所有的注释必须被持续维护或者干脆就删除。
 
-
-Block comments should generally be avoided, as code should be as self-documenting as possible, with only the need for intermittent, few-line explanations. *Exception: This does not apply to those comments used to generate documentation.*
-
 块注释应该被避免，代码本身应该尽可能就像文档一样表示意图，只需要很少的打断注释  *例外： 这不能适用于用来产生文档的注释*
 
-### Header Documentation  头文档
-
-The documentation of class should be done using the Doxygen/AppleDoc syntax only in the .h files when possible. Documentation should be provided for methods and properties.
-
+###  头文档
 
 一个类的文档应该只在 .h 文件里用 Doxygen/AppleDoc 的语法书写。 方法和属性都应该提供文档。