forked from zh-google-styleguide/zh-google-styleguide
-
Notifications
You must be signed in to change notification settings - Fork 1
/
formatting.html
597 lines (506 loc) · 15.4 KB
/
formatting.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>formatting</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<style type="text/css">
/* GitHub stylesheet for MarkdownPad (http://markdownpad.com) */
/* Author: Nicolas Hery - http://nicolashery.com */
/* Version: 29d1c5bc36da364ad5aa86946d420b7bbc54a253 */
/* Source: https://github.com/nicolahery/markdownpad-github */
/* RESET
=============================================================================*/
html, body, div, span, applet, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote, pre, a, abbr, acronym, address, big, cite, code, del, dfn, em, img, ins, kbd, q, s, samp, small, strike, strong, sub, sup, tt, var, b, u, i, center, dl, dt, dd, ol, ul, li, fieldset, form, label, legend, table, caption, tbody, tfoot, thead, tr, th, td, article, aside, canvas, details, embed, figure, figcaption, footer, header, hgroup, menu, nav, output, ruby, section, summary, time, mark, audio, video {
margin: 0;
padding: 0;
border: 0;
}
/* BODY
=============================================================================*/
body {
font-family: Helvetica, arial, freesans, clean, sans-serif;
font-size: 14px;
line-height: 1.6;
color: #333;
background-color: #fff;
padding: 20px;
max-width: 960px;
margin: 0 auto;
}
body>*:first-child {
margin-top: 0 !important;
}
body>*:last-child {
margin-bottom: 0 !important;
}
/* BLOCKS
=============================================================================*/
p, blockquote, ul, ol, dl, table, pre {
margin: 15px 0;
}
/* HEADERS
=============================================================================*/
h1, h2, h3, h4, h5, h6 {
margin: 20px 0 10px;
padding: 0;
font-weight: bold;
-webkit-font-smoothing: antialiased;
}
h1 tt, h1 code, h2 tt, h2 code, h3 tt, h3 code, h4 tt, h4 code, h5 tt, h5 code, h6 tt, h6 code {
font-size: inherit;
}
h1 {
font-size: 28px;
color: #000;
}
h2 {
font-size: 24px;
border-bottom: 1px solid #ccc;
color: #000;
}
h3 {
font-size: 18px;
}
h4 {
font-size: 16px;
}
h5 {
font-size: 14px;
}
h6 {
color: #777;
font-size: 14px;
}
body>h2:first-child, body>h1:first-child, body>h1:first-child+h2, body>h3:first-child, body>h4:first-child, body>h5:first-child, body>h6:first-child {
margin-top: 0;
padding-top: 0;
}
a:first-child h1, a:first-child h2, a:first-child h3, a:first-child h4, a:first-child h5, a:first-child h6 {
margin-top: 0;
padding-top: 0;
}
h1+p, h2+p, h3+p, h4+p, h5+p, h6+p {
margin-top: 10px;
}
/* LINKS
=============================================================================*/
a {
color: #4183C4;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
/* LISTS
=============================================================================*/
ul, ol {
padding-left: 30px;
}
ul li > :first-child,
ol li > :first-child,
ul li ul:first-of-type,
ol li ol:first-of-type,
ul li ol:first-of-type,
ol li ul:first-of-type {
margin-top: 0px;
}
ul ul, ul ol, ol ol, ol ul {
margin-bottom: 0;
}
dl {
padding: 0;
}
dl dt {
font-size: 14px;
font-weight: bold;
font-style: italic;
padding: 0;
margin: 15px 0 5px;
}
dl dt:first-child {
padding: 0;
}
dl dt>:first-child {
margin-top: 0px;
}
dl dt>:last-child {
margin-bottom: 0px;
}
dl dd {
margin: 0 0 15px;
padding: 0 15px;
}
dl dd>:first-child {
margin-top: 0px;
}
dl dd>:last-child {
margin-bottom: 0px;
}
/* CODE
=============================================================================*/
pre, code, tt {
font-size: 12px;
font-family: Consolas, "Liberation Mono", Courier, monospace;
}
code, tt {
margin: 0 0px;
padding: 0px 0px;
white-space: nowrap;
border: 1px solid #eaeaea;
background-color: #f8f8f8;
border-radius: 3px;
}
pre>code {
margin: 0;
padding: 0;
white-space: pre;
border: none;
background: transparent;
}
pre {
background-color: #f8f8f8;
border: 1px solid #ccc;
font-size: 13px;
line-height: 19px;
overflow: auto;
padding: 6px 10px;
border-radius: 3px;
}
pre code, pre tt {
background-color: transparent;
border: none;
}
/* QUOTES
=============================================================================*/
blockquote {
border-left: 4px solid #DDD;
padding: 0 15px;
color: #777;
}
blockquote>:first-child {
margin-top: 0px;
}
blockquote>:last-child {
margin-bottom: 0px;
}
/* HORIZONTAL RULES
=============================================================================*/
hr {
clear: both;
margin: 15px 0;
height: 0px;
overflow: hidden;
border: none;
background: transparent;
border-bottom: 4px solid #ddd;
padding: 0;
}
/* TABLES
=============================================================================*/
table th {
font-weight: bold;
}
table th, table td {
border: 1px solid #ccc;
padding: 6px 13px;
}
table tr {
border-top: 1px solid #ccc;
background-color: #fff;
}
table tr:nth-child(2n) {
background-color: #f8f8f8;
}
/* IMAGES
=============================================================================*/
img {
max-width: 100%
}
</style>
</head>
<body>
<h1>格式</h1>
<pre><code>代码风格和格式确实比较随意, 但一个项目中所有人遵循同一风格是非常容易的.
个体未必同意下述每一处格式规则, 但整个项目服从统一的编程风格是很重要的,
只有这样才能让所有人能很轻松的阅读和理解代码.
此文档同时提供了代码格式模板文件.
</code></pre>
<h2>cpplint</h2>
<pre><code>Google提供了代码检查工具 `cpplint` , 我们对此工具进行了修改.
所有代码提交前都需要使用此工具进行检查.
此工具使用python编写, 随此文档提供.
</code></pre>
<h2>行长度</h2>
<pre><code>每一行代码字符数不超过 80.
</code></pre>
<dl>
<dt>优点:</dt>
<dd>
<p>提倡该原则的人主张强迫他们调整编辑器窗口大小很野蛮.
很多人同时并排开几个代码窗口, 根本没有多余空间拉伸窗口.
大家都把窗口最大尺寸加以限定, 并且 80 列宽是传统标准.
为什么要改变呢?</p>
</dd>
<dt>缺点:</dt>
<dd>
<p>反对该原则的人则认为更宽的代码行更易阅读. 80 列的限制是上个世纪 60
年代的大型机的古板缺陷; 现代设备具有更宽的显示屏,
很轻松的可以显示更多代码.</p>
</dd>
<dt>结论:</dt>
<dd>
<p>80 个字符是最大值.</p>
<p>特例:</p>
<ul>
<li>
如果一行注释包含了超过 80 字符的命令或 URL,
出于复制粘贴的方便允许该行超过 80 字符.
</li>
<li>包含长路径的 <code>#include</code> 语句可以超出80列. 但应该尽量避免.</li>
<li>头文件保护 <define_guard> 可以无视该原则.</li>
</ul>
</dd>
</dl>
<h2>非 ASCII 字符</h2>
<pre><code>尽量不使用非 ASCII 字符, 使用时必须使用 UTF-8 编码.
</code></pre>
<p>即使是英文, 也不应将用户界面的文本硬编码到源代码中, 因此非 ASCII
字符要少用. 特殊情况下可以适当包含此类字符. 如, 代码分析外部数据文件时,
可以适当硬编码数据文件中作为分隔符的非 ASCII 字符串; 更常见的是
(不需要本地化的) 单元测试代码可能包含非 ASCII 字符串. 此类情况下, 应使用
UTF-8 编码, 因为很多工具都可以理解和处理 UTF-8 编码. 十六进制编码也可以,
能增强可读性的情况下尤其鼓励 —— 比如 <code>"\xEF\xBB\xBF"</code> 在 Unicode 中是
<em>零宽度 无间断</em> 的间隔符号, 如果不用十六进制直接放在 UTF-8 格式的源文件中, 是看不到的.</p>
<h2>空格还是制表位</h2>
<pre><code>只使用空格, 每次缩进 2 个空格.
</code></pre>
<p>我们使用空格缩进. 不要在代码中使用制符表.
你应该设置编辑器将制符表转为空格.</p>
<h2>函数声明与定义</h2>
<pre><code>返回类型和函数名在同一行, 参数也尽量放在同一行.
</code></pre>
<p>函数看上去像这样:</p>
<pre><code>ReturnType ClassName::FunctionName(Type par_name1, Type par_name2)
{
DoSomething();
...
}
</code></pre>
<p>如果同一行文本太多, 放不下所有参数:</p>
<pre><code>ReturnType ClassName::ReallyLongFunctionName(Type par_name1,
Type par_name2,
Type par_name3)
{
DoSomething();
...
}
</code></pre>
<p>甚至连第一个参数都放不下:</p>
<pre><code>ReturnType LongClassName::ReallyReallyReallyLongFunctionName(
Type par_name1, // 4 space indent
Type par_name2,
Type par_name3)
{
DoSomething(); // 2 space indent
...
}
</code></pre>
<p>注意以下几点:</p>
<ul>
<li>返回值总是和函数名在同一行;</li>
<li>左圆括号总是和函数名在同一行;</li>
<li>函数名和左圆括号间没有空格;</li>
<li>圆括号与参数间没有空格;</li>
<li>左大括号总在最后一个参数同一行的末尾处;</li>
<li>右大括号总是单独位于函数最后一行;</li>
<li>右圆括号和左大括号间总是有一个空格;</li>
<li>函数声明和实现处的所有形参名称必须保持一致;</li>
<li>所有形参应尽可能对齐;</li>
<li>缺省缩进为 2 个空格;</li>
<li>换行后的参数保持 4 个空格的缩进;</li>
</ul>
<p>如果函数声明成 <code>const</code>, 关键字 <code>const</code> 应与最后一个参数位于同一行:=</p>
<pre><code>// Everything in this function signature fits on a single line
ReturnType FunctionName(Type par) const
{
...
}
// This function signature requires multiple lines, but
// the const keyword is on the line with the last parameter.
ReturnType ReallyLongFunctionName(Type par1,
Type par2) const
{
...
}
</code></pre>
<h2>函数调用</h2>
<pre><code>尽量放在同一行, 否则, 将实参封装在圆括号中.
</code></pre>
<p>函数调用遵循如下形式:</p>
<pre><code>bool retval = DoSomething(argument1, argument2, argument3);
</code></pre>
<p>如果同一行放不下, 可断为多行, 后面每一行都和第一个实参对齐, 左圆括号后和右圆括号前不要留空格:</p>
<pre><code>bool retval = DoSomething(averyveryveryverylongargument1,
argument2, argument3);
</code></pre>
<p>如果函数参数很多, 出于可读性的考虑可以在每行只放一个参数:</p>
<pre><code>bool retval = DoSomething(argument1,
argument2,
argument3,
argument4);
</code></pre>
<h2>条件语句</h2>
<pre><code>倾向于不在圆括号内使用空格. 关键字 `else` 另起一行.
</code></pre>
<p>示例代码如下:</p>
<pre><code>if (condition)// no spaces inside parentheses
{// new line
...
}
else// new line
{// new line
...
}
</code></pre>
<h2>循环和开关选择语句</h2>
<ul>
<li><code>switch</code> 语句可以使用大括号分段. 空循环体应使用 <code>{}</code> 或 <code>continue</code>.</li>
<li>
<code>switch</code> 语句中的 <code>case</code> 块可以使用大括号也可以不用, 取决于你的个人喜好.
示例代码如下
switch (var)
{
case 0:
...
break;
case 1:
...
break;
default:
assert(false);
break;
}
</li>
</ul>
<h2>指针和引用表达式</h2>
<pre><code>句点或箭头前后不要有空格. 指针/地址操作符 (`*, &`) 之后不能有空格.
</code></pre>
<p>示例如下:</p>
<pre><code>x = *p;
p = &x;
x = r.y;
x = r->y;
</code></pre>
<p>注意:</p>
<ul>
<li>在访问成员时, 句点或箭头前后没有空格.</li>
<li>指针操作符 <code>*</code> 或 <code>&</code> 后没有空格.</li>
</ul>
<h2>函数返回值</h2>
<pre><code>`return` 表达式中不要用圆括号包围.
</code></pre>
<p>8.11. 变量及数组初始化
用 <code>=</code> 或 <code>()</code> 均可.</p>
<p>在二者中做出选择; 下面的方式都是正确的:</p>
<pre><code>int x = 3;
int x(3);
string name("Some Name");
string name = "Some Name";
</code></pre>
<h2>预处理指令</h2>
<pre><code>预处理指令不要缩进, 从行首开始.
即使预处理指令位于缩进代码块中, 指令也应从行首开始.
</code></pre>
<p>示例如下</p>
<pre><code> // Good - directives at beginning of line
if (lopsided_score)
{
#if DISASTER_PENDING // Correct -- Starts at beginning of line
DropEverything();
#endif
BackToNormal();
}
</code></pre>
<h2>类格式</h2>
<pre><code>访问控制块的声明依次序是 `public:`, `protected:`, `private:`, 每次缩进 1 个空格.
</code></pre>
<p>示例如下:</p>
<pre><code>class MyClass : public OtherClass
{
public: // Note the 1 space indent!
MyClass(); // Regular 2 space indent.
explicit MyClass(int var);
~MyClass() {}
void SomeFunction();
void SomeFunctionThatDoesNothing()
void setSome_var(int var) { some_var_ = var; }
int getSome_var() const { return some_var_; }
private:
bool SomeInternalFunction();
int some_var_;
int some_other_var_;
DISALLOW_COPY_AND_ASSIGN(MyClass);
};
</code></pre>
<p>注意事项:</p>
<ul>
<li>所有基类名应在 80 列限制下尽量与子类名放在同一行.</li>
<li>关键词 <code>public:</code>, <code>protected:</code>, <code>private:</code> 要缩进 1 个空格.</li>
<li>
除第一个关键词 (一般是 <code>public</code>) 外, 其他关键词前要空一行.
如果类比较小的话也可以不空.
</li>
<li>这些关键词后不要保留空行.</li>
<li><code>public</code> 放在最前面, 然后是 <code>protected</code>, 最后是 <code>private</code>.</li>
<li>关于声明顺序的规则请参考 声明顺序一节.</li>
</ul>
<h2>初始化列表</h2>
<pre><code>构造函数初始化列表放在同一行或按四格缩进并排几行.
</code></pre>
<p>下面两种初始化列表方式都可以接受:</p>
<pre><code>// When it all fits on one line:
MyClass::MyClass(int var) : some_var_(var), some_other_var_(var + 1)
{
...
}
// When it requires multiple lines, indent 4 spaces, putting the colon on
// the first initializer line:
MyClass::MyClass(int var) :
some_var_(var), // 4 space indent
some_other_var_(var + 1) // lined up
{
...
}
</code></pre>
<h2>名字空间格式化</h2>
<pre><code>名字空间内容执行标准缩进(2个空格).
</code></pre>
<p>示例如下:</p>
<pre><code>namespace abc
{
void foo()
{
...
}
} // namespace abc
</code></pre>
<h2>水平留白</h2>
<ul>
<li>水平留白的使用因地制宜. 永远不要在行尾添加没意义的留白.</li>
<li>添加冗余的留白会给其他人编辑时造成额外负担. 因此, 行尾不要留空格.</li>
<li>如果确定一行代码已经修改完毕, 将多余的空格去掉, 或者在专门清理空格时去掉（确信没有其他人在处理). </li>
</ul>
<h2>垂直留白</h2>
<pre><code>垂直留白越少越好.
</code></pre>
<ul>
<li>这不仅仅是规则而是原则问题了: 不在万不得已, 不要使用空行. 尤其是:
两个函数定义之间的空行不要超过 2 行, 函数体首尾不要留空行,
函数体中也不要随意添加空行.</li>
<li>基本原则是: 同一屏可以显示的代码越多, 越容易理解程序的控制流. 当然,
过于密集的代码块和过于疏松的代码块同样难看, 取决于你的判断.
但通常是垂直留白越少越好.</li>
</ul>
</body>
</html>
<!-- This document was created with MarkdownPad, the Markdown editor for Windows (http://markdownpad.com) -->