forked from kazurof/GoogleJavaStyle-ja
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
631 lines (620 loc) · 52.2 KB
/
index.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
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="style.css"/>
<title>Google Java Style Guide (非公式和訳)</title>
<meta name="keywords" content="java, Google,コーディング規約">
<meta name="description" content="本文書はGoogleのJavaコーディング規約である Google Java Style Guide の非公式和訳です。">
</head>
<body>
<h1 class="title">Google Java Style Guide(非公式和訳)</h1>
<hr />
<h2 style="vertical-align:middle;">この文書について</h2>
<p>本文書はGoogleのJavaコーディング規約であるところの <a href="https://google.github.io/styleguide/javaguide.html">Google Java Style Guide</a> の非公式和訳です。
<a href="https://github.com/google/styleguide/commit/911d9f4a7e3020578f4609860d7e5ede422a8f28#diff-b6c9191ee5ccb7a5ef170e98e51d94d8">2017/09/30</a> の版を使っています。技術的に正確である事を意図して訳してありますが、どこかで間違えているかもしれません。本家は随時更新される様子ですが、こちらが追いつかなくなるかもしれません。生暖かく見守ってやってください。誤訳、誤植の指摘を歓迎いたします。</p>
<p>本文書はCC-By 3.0 Licenseにてライセンスされます。（翻訳元文書に基づく）詳細は <a href="https://creativecommons.org/licenses/by/3.0/">https://creativecommons.org/licenses/by/3.0/</a> をご覧ください。</p>
<hr />
<table border="0">
<tr>
<td>
<p class="indexgroup"><a href="#s1-introduction">1 <strong>導入</strong></a></p>
<div class="lv1"><a href="#s1-1-terminology">1.1 用語についての注記</a><br />
<a href="#s1-2-guide-notes">1.2 ガイドについての注記</a></div>
<p class="indexgroup"><a href="#s2-source-file-basics">2 <strong>ソースファイルの基本事項</strong></a></p>
<div class="lv1"><a href="#s2-1-file-name">2.1 ファイル名</a><br />
<a href="#s2-2-file-encoding">2.2 ファイルエンコーディング：UTF-8</a><br />
<a href="#s2-3-special-characters">2.3 特殊文字</a></div>
<p class="indexgroup"><a href="#s3-source-file-structure">3 <strong>ソースファイル構造</strong></a></p>
<div class="lv1"><a href="#s3-1-copyright-statement">3.1 ライセンスあるいはコピーライトの情報（もしあるならば）</a><br />
<a href="#s3-2-package-statement">3.2 パッケージ文</a><br />
<a href="#s3-3-import-statements">3.3 インポート文</a></div>
<div class="lv1"><a href="#s3-4-class-declaration">3.4 クラス宣言</a></div>
<p class="indexgroup"><a href="#s4-formatting">4 <strong>フォーマット</strong></a></p>
<div class="lv1"><a href="#s4-1-braces">4.1 中括弧</a></div>
<div class="lv1"><a href="#s4-2-block-indentation">4.2 ブロックのインデントは空白2個である</a></div>
<div class="lv1"><a href="#s4-3-one-statement-per-line">4.3 1行毎に1個の文</a></div>
<div class="lv1"><a href="#s4-4-column-limit">4.4 1行の文字数制限 100文字</a></div>
<div class="lv1"><a href="#s4-5-line-wrapping">4.5 行の折り返し</a></div>
<p></td><td></p>
<div class="lv1"><a href="#s4-6-whitespace">4.6 空白</a></div>
<div class="lv1"><a href="#s4-7-grouping-parentheses">4.7 グループ化の括弧 推奨</a></div>
<div class="lv1"><a href="#s4-8-specific-constructs">4.8 各構造物</a></div>
<p class="indexgroup"><a href="#s5-naming">5 <strong>命名</strong></a></p>
<div class="lv1"><a href="#s5-1-identifier-names">5.1 すべての識別子への共通ルール</a><br />
<a href="#s5-2-specific-identifier-names">5.2 識別子の種類ごとのルール</a></div>
<div class="lv1"><a href="#s5-3-camel-case">5.3 キャメルケースの定義</a></div>
<p class="indexgroup"><a href="#s6-programming-practices">6 <strong>プログラミングの実践</strong></a></p>
<div class="lv1"><a href="#s6-1-override-annotation">6.1 @Override：常に使う</a><br />
<a href="#s6-2-caught-exceptions">6.2 キャッチされた例外：無視しない</a><br />
<a href="#s6-3-static-members">6.3 staticなメンバー：クラスを使って修飾する</a><br />
<a href="#s6-4-finalizers">6.4 ファイナライザ：使わない</a></div>
<p class="indexgroup"><a href="#s7-javadoc">7 <strong>Javadoc</strong></a></p>
<div class="lv1"><a href="#s7-1-javadoc-formatting">7.1 フォーマット</a></div>
<div class="lv1"><a href="#s7-2-summary-fragment">7.2 要約の記述</a><br />
<a href="#s7-3-javadoc-where-required">7.3 Javadocが使われる場所</a></div>
</td>
</tr>
</table>
<h2 id="s1-introduction">1 導入</h2>
<p>この文書はJava <sup>TM</sup> プログラミング言語のソースコードのGoogleのコーディング標準の <strong>完全</strong> な定義を提供する。下記のルールに従うJavaソースファイルのみが、Googleスタイルであるとみなされる。</p>
<p>他のプログラミングスタイルガイドのように、問題の対象範囲は審美的なフォーマットの問題だけでなく他の種類の規約やコーディング標準も含まれる。しかしながらこの文書は私達が全世界的に従う <strong>当然の規則</strong> に優先的に注力しており（人間やマシンのいずれでも）明確に実施できない助言をすることを避けている。</p>
<h3 id="s1-1-terminology">1.1 用語についての注記</h3>
<p>本文書において、特別に断りのない限り、</p>
<ol>
<li>クラスという用語は、「通常の」クラス、列挙型 、インターフェース、アノテーション型(@interface)を包括的に意味する。</li>
<li>（クラスの）メンバという用語は、ネストしたクラス、フィールド、メソッド、コンストラクタ、つまり初期化子とコメントを除いた全てのトップレベルの内容を包括的に意味する。</li>
<li>コメントという用語は、常に実装のコメントを意味する。「ドキュメンテーションコメント」という言い方は使わない。代わりに共通の言葉である「Javadoc」を使う。</li>
</ol>
<p>本文書では他の用語の注記は適宜行われる。</p>
<h3 id="s1-2-guide-notes">1.2 ガイドについての注記</h3>
<p>この文書内のサンプルコードは <strong>参考</strong> (Non-Normative)である。 つまり、例がGoogleスタイル文書に書かれていても、それはコードを記述するための <em>唯一の</em> 方法ではない場合がある。例に出される補足的なフォーマットの仕方はルールとして強調されるべきではない。</p>
<h2 id="s2-source-file-basics">2 ソースファイルの基本事項</h2>
<h3 id="s2-1-file-name">2.1 ファイル名</h3>
<p>ソースファイル名はそのファイルに(正確に1つ)入っているトップレベルクラスの大文字小文字を区別した名前に加えて <code>.java</code> という拡張子が付いていること。</p>
<h3 id="s2-2-file-encoding">2.2 ファイルエンコーディング：UTF-8</h3>
<p>ソースファイルは <strong><span class="caps">UTF</span>-8</strong> でエンコードされていること。</p>
<h3 id="s2-3-special-characters">2.3 特殊文字</h3>
<h4 id="s2-3-1-whitespace-characters">2.3.1 空白</h4>
<p>改行以外では、 <strong><span class="caps">ASCII</span> 水平スペース文字 (0×20)</strong> はソース内でどこに現れても良い唯一の空白文字である。以下のことを意味する。</p>
<ol>
<li>Stringと文字リテラルでのこれ以外の空白文字はエスケープされること。</li>
<li>タブ文字をインデントの目的で <strong>使ってはならない。</strong></li>
</ol>
<h4 id="s2-3-2-special-escape-sequences">2.3.2 特別なエスケープシーケンス</h4>
<p>特別なエスケープシーケンスを持つ全ての文字(<code>\b, \t, \n, \f, \r, \", \' と \\</code>)については8進数表記(<code>\012</code>)やUnicodeエスケープ(<code>\u000a</code>)でなく、通常のエスケープシーケンスで表記する。</p>
<h4 id="s2-3-3-non-ascii-characters">2.3.3 非ASCII文字</h4>
<p>残りの非ASCII文字については実際のUnicode文字（例：∞）あるいは同等のUnicodeエスケープ(例： \u221e)が使われる。<br />
この選択は <strong>ソースコードを読むことや理解することが簡単になる</strong> かどうかのみに依存するが、文字列リテラルやコメント以外でのUnicodeエスケープは強く推奨されない。</p>
<blockquote>
<p><strong>Tip:</strong> Unicodeエスケープの場合時たま実際にUnicode文字が使われている時でも、説明のコメントがあるとわかりやすい。</p>
</blockquote>
<table>
<tr>
<td>例 </td>
<td>説明</td>
</tr>
<tr>
<td><code>String unitAbbrev = "μs";</code> </td>
<td>最良。コメントなしでも完全で明確。</td>
</tr>
<tr>
<td><code>String unitAbbrev = "\u03bcs"; // "μs"</code> </td>
<td>許容される。しかしこう書く理由はない。</td>
</tr>
<tr>
<td><code>String unitAbbrev = "\u03bcs"; // ギリシャ文字ミューと "s"</code> </td>
<td>許容される。しかし奇妙で間違えやすい。</td>
</tr>
<tr>
<td><code>String unitAbbrev = "\u03bcs";</code> </td>
<td>だめ。読者はこれが何なのか分からない。</td>
</tr>
<tr>
<td><code>return '\ufeff' + content; // バイトオーダーマーク</code> </td>
<td>良い。表示されない文字にはエスケープを使い必要ならコメントする。</td>
</tr>
</table>
<blockquote>
<p><strong>Tip:</strong> ただ何かのプログラムが非ASCII文字を正しく処理しないという危惧だけでコードを読みにくくしてはならない。もしそのような事が起こる場合はそのプログラムが <strong>壊れている</strong> のであってそちらが <strong>修正</strong> されるべきである。</p>
</blockquote>
<h2 id="s3-source-file-structure">3 ソースファイル構造</h2>
<p>ソースファイルの内容は <strong>以下の順序</strong> であること。</p>
<p>1. ライセンスあるいはコピーライトの情報（もしあるならば）<br />
2. package文<br />
3. import文<br />
4. ただ1個のトップレベルクラス。</p>
<p>ソースに書かれている内容それぞれの分離には <strong>ただ1行の空行</strong> を使うこと。</p>
<h3 id="s3-1-copyright-statement">3.1 ライセンスあるいはコピーライトの情報（もしあるならば）</h3>
<p>もしファイルにライセンスあるいはコピーライトの情報があるならばここに入る。</p>
<h3 id="s3-2-package-statement">3.2 パッケージ文</h3>
<p>パッケージ文は <strong>改行してはならない。</strong> 文字数制限（4.4節 <a href="#s4-4-column-limit">文字数制限は100文字</a> ）はパッケージ文には適用されない。</p>
<h3 id="s3-3-import-statements">3.3 インポート文</h3>
<h4 id="s3-3-1-wildcard-imports">3.3.1 ワイルドカードインポートは禁止</h4>
<p><strong>ワイルドカードインポート</strong> はstaticであってもなくても <strong>使ってはならない。</strong></p>
<h4 id="s3-3-2-import-line-wrapping">3.3.2 改行禁止</h4>
<p>import文は <strong>改行してはならない。</strong> 文字数制限（4.4節 <a href="#s4-4-column-limit">文字数制限は100文字</a> ）はimport文には適用されない。</p>
<h4 id="s3-3-3-import-ordering-and-spacing">3.3.3 順序と空白</h4>
<p>インポート文は以下の順序で並べられる。</p>
<ol>
<li>全てのstaticインポートを単一のブロックでまとめる。</li>
<li>全ての非staticインポートを単一のブロックでまとめる。</li>
</ol>
<p>もしもstaticインポートと非staticインポートの両方があるなら、一つの空行が両者を分離する。import節間に、空行は存在しない。</p>
<p>各ブロック内で、importされた名前はASCII順序で並べられる。（ <strong>注釈：</strong> このことはインポート文全体がASCII順になっていることと同じではない。なぜなら ‘.’ は’;’ より先にソートされるからである。）</p>
<h4 id="s3-3-4-import-class-not-static">3.3.4 クラスをstatic importしない</h4>
<p>staticなネストしたクラスをimportするのにstatic importを使わない。それらは通常のインポートで使われる。</p>
<h3 id="s3-4-class-declaration">3.4 クラス宣言</h3>
<h4 id="s3-4-1-one-top-level-class">3.4.1 1個だけのトップレベルクラスの宣言</h4>
<p>各トップレベルクラスは1個のファイルに保存される。</p>
<h4 id="s3-4-2-class-member-ordering">3.4.2 クラスメンバーの順序</h4>
<p>クラスメンバーや初期化子の順序の選択はわかりやすさに多大な影響を与える。しかしながら唯一の解法は無い。クラスが異なれば内容は異なった順序で並べられる。</p>
<p>重要な事はそれぞれのクラスはそのメンバーを <strong>何らかの合理的な順序</strong> で並べ、クラスのメンテナンスをする人が尋ねられた時に答えられるようなることである。例えば新しいメソッドはクラスの最後に入れることが慣例であるかのように追加されてはならない。それは「追加された日の順」という結果になるだけであって、合理的な順序ではない。</p>
<h5>3.4.2.1 オーバーロードしているメソッド群を分離してはならない</h5>
<p>クラスに複数のコンストラクタや同じ名前を持つメソッドがある場合は、別のコードを（privateなメンバであっても）入れることなく連続して並べる。</p>
<h2 id="s4-formatting">4 フォーマット</h2>
<p><strong>用語についての注釈：</strong> 「ブロック様の構造物(block-like construct)」とは、クラス、メソッド、コンストラクタの本体を指す。すべての配列初期化子は任意に「ブロック様の構造物」とみなされて良い。4.8.3.1節 <a href="#s4-8-3-1-array-initializers">配列初期化子</a> を参照。</p>
<h3 id="s4-1-braces">4.1 中括弧</h3>
<h4 id="s4-1-1-braces-always-used">4.1.1 使えるところでは中括弧は使う</h4>
<p>中括弧は <code>if else for do while</code> 文において本体が空でも1行しかなくても使われる。</p>
<h4 id="s4-1-2-blocks-k-r-style">4.1.2 空でないブロック：K&Rスタイル</h4>
<p>中括弧は空でないブロックや、ブロック様の構造物ではカーニハン・リッチースタイル(<a href="https://www.codinghorror.com/blog/2012/07/new-programming-jargon.html">Egyptian Brackets</a> )に従う。</p>
<ul>
<li>開始中括弧の前に改行を入れない。</li>
<li>開始中括弧の後に改行を入れる。</li>
<li>終了中括弧の前に改行を入れる。</li>
<li>終了中括弧の後に改行を入れる。但し、終了中括弧が文やメソッドの本体を終える時のみである。例えば終了中括弧の後に <code>else</code> や、カンマが続く場合は改行をしない。</li>
</ul>
<p>例：</p>
<pre>
return () -> {
while (condition()) {
method();
}
};
return new MyClass() {
@Override public void method() {
if (condition()) {
try {
something();
} catch (ProblemException e) {
recover();
}
} else if (otherCondition()) {
somethingElse();
} else {
lastThing();
}
}
};
</pre>
<p>列挙型でのいくつかの例外は、4.8.1節 <a href="#s4-8-1-enum-classes">列挙型</a> にて示される。</p>
<h4 id="s4-1-3-braces-empty-blocks">4.1.3 空ブロックは簡潔に</h4>
<p>空ブロックやブロック様の構造物は(Section 4.1.2で示したように) K & R スタイルでもよい。<br />
また、開始括弧直後で( <code>{}</code> ) の間に文字や改行無しで閉じてよい。 <strong>但し、</strong> <code>if/else</code> あるいは <code>try/catch/finally</code> のような複数ブロックの文の場合を除く。</p>
<p>例：</p>
<pre>
// これは問題ない
void doNothing() {}
// これも同様に問題ない
void doNothing() {
}
</pre>
<pre>
// これは問題がある。複数ブロックの文では簡単な空ブロックをつかってはならない。
try {
doSomething();
} catch (Exception e) {}
</pre>
<h3 id="s4-2-block-indentation">4.2 ブロックのインデントは空白2個である</h3>
<p>新しいブロックあるいはブロック様の構造物が開始した時インデントは空白2個づつ増える。ブロックが終了したら、インデントは1個前のレベルに戻る。インデントレベルはブロックを通じてコードとコメントに適用される。4.1.2節の例を参照のこと。（ <a href="#s4-1-2-blocks-k-r-style">空でないブロック：K&Rスタイル</a> ）</p>
<h3 id="s4-3-one-statement-per-line">4.3 1行毎に1個の文</h3>
<p>各文の末尾は改行でなくてはならない。</p>
<h3 id="s4-4-column-limit">4.4 1行の文字数制限 100文字</h3>
<p>Java コードの1行の文字数制限は100文字である。文字とは任意のUnicodeコードポイントを意味する。 以下の例外を除き、この制限を超えた行は4.5節 <a href="#s4-5-line-wrapping">行の折り返し</a> で述べるように改行されなくてはならない。</p>
<p><strong>Tip:</strong> 画面表示上の大小が違っていても、それぞれのUnicodeコードポイントを１個と数える。例えば<a href="https://ja.wikipedia.org/wiki/%E5%85%A8%E8%A7%92%E3%81%A8%E5%8D%8A%E8%A7%92">全角文字</a>を使う場合、この規約を厳密に守る箇所では制限に達する前に改行して良い。</p>
<p><strong>例外：</strong></p>
<p>1. 文字数制限に従うのが不可能の場合。（例えば、Javadoc内の長いURL、長いJSNIメソッド<sup class="footnote" id="fnr1"><a href="#fn1">1</a></sup>参照）<br />
2. パッケージ文とインポート文 （3.2 <a href="#s3-2-package-statement">パッケージ文</a> と 3.3 <a href="#s3-3-import-statements">インポート文</a> を参照のこと）<br />
3. コメント内の、コンソールにコピー＆ペーストされるようなコマンド。</p>
<p class="footnote" id="fn1"><a href="#fnr1"><sup>1</sup></a> 訳注：JavaScript Native Interface 。Google Web Tookit においてアプリからJavaScript コードを呼ぶことができる。</p>
<h3 id="s4-5-line-wrapping">4.5 行の折り返し</h3>
<p><strong>用語の注記：</strong> ある意味では規約に合致している1行のコードを複数行に分けた場合、この行為を行の折り返しと呼ぶ。</p>
<p>どんな状況にも合う改行方法を正確に示すような統一的で決定的なやり方は存在しない。同じコードを改行する正しい方法は複数存在する。</p>
<p><strong>注記：</strong> 改行の典型的な理由は1行の文字数制限を超えることを避けることであるが、文字数制限を実際に満たしているコードであっても作者の裁量で改行される場合がある。</p>
<blockquote>
<p><strong>Tip:</strong> メソッドやローカル変数の抽出をすれば、改行をせずに問題を解決できる場合がある。</p>
</blockquote>
<h4 id="s4-5-1-line-wrapping-where-to-break">4.5.1 どこで改行するか</h4>
<p>改行の第一原則は、 <strong>高い文法のレベル</strong> で改行することである。また、</p>
<ol>
<li>代入でない演算子で改行するときは、シンボルの前で改行する。（これはJavaScriptやC++のような他の言語のGoogleスタイルの慣習とは異なることに注意すること。）
<ul>
<li>このことは、以下の「演算子ライクな」シンボルにも適用される。
<ul>
<li>ドット演算子( <code>.</code> )</li>
<li>メソッド参照でのコロン２個( <code>::</code> )</li>
<li>型演算子の & 記号( <code><T extends Foo & Bar></code> )</li>
<li>catch節でのパイプ記号 ( <code>catch (FooException | BarException e)</code> )</li>
</ul></li>
</ul></li>
<li>行が代入演算子で改行されるときは、通常シンボルの後ろで改行される。しかしどちらの方法でも問題はない。
<ul>
<li>このことは拡張 <code>for</code> (“foreach”) 文の「代入演算子のような」コロンにも適用される。</li>
</ul></li>
<li>メソッドやコンストラクタ名に続く開始括弧（ <code>(</code> ）は直後に続いて書かれる。</li>
<li>カンマ( <code>,</code> )はその前のトークンの直後に続いて書かれる。</li>
<li>行はラムダの矢印の隣で改行されることはない。但しラムダの本体が単一のカッコなしの式である場合は矢印の直後で改行して良い。</li>
</ol>
<p>例：</p>
<pre>
MyLambda<String, Long, Object> lambda =
(String label, Long value, Object obj) -> {
...
};
Predicate<String> predicate = str ->
longExpressionInvolving(str);
</pre>
<p><strong>注記：</strong> 改行の第一目的はコードを明確にすることである。行数が小さくなるようにコードを書く必要はない。</p>
<h4 id="s4-5-2-line-wrapping-indent">4.5.2 連続する行は少なくとも４文字インデントする</h4>
<p>改行の際、連続する先頭行に続く各行は少なくとも空白4個分、元からインデントする。</p>
<p>複数の連続した行がある場合、インデントは4以上ならいくつでも良い。一般的に、2個の連続した行が同じインデントレベルであることは、文法的に相似の要素であることと同じである。</p>
<p>4.6.3節の <a href="#s4-6-3-horizontal-alignment">水平位置揃え：全く不要</a> は、あるトークンを前の行に揃えるためいくつかの空白を入れるという非推奨のやり方を防ぐものである。</p>
<h3 id="s4-6-whitespace">4.6 空白</h3>
<h4 id="s4-6-1-vertical-whitespace">4.6.1 垂直の空白</h4>
<p>単一の空行は、以下の場合で使われる。</p>
<ol>
<li>クラスの連続するメンバか初期化子の間。フィールド、コンストラクタ、メソッド、ネストしたクラス、static初期化子、インスタンス初期化子。
<ul>
<li><strong>例外</strong> ：2個の連続するフィールド（その間にコードがないもの）間での空行は任意である。そのような空行はフィールドの <em>論理的なグループ分け</em> をするのに必要である。</li>
<li><strong>例外</strong> ：enum 定数間の改行は 4.8.1. 節で議論される</li>
</ul></li>
<li>ステートメントの間で、コードを論理的にグループ分けしたいため。</li>
<li>必要な場合、クラスの最初のメンバーあるいは初期化子の前と最終メンバーあるいは初期化子の後。（推奨も禁止もしない）</li>
<li>本文書の別の節で入れるよう求められた場所（3節の <a href="#s3-source-file-structure">ソースファイル構造</a> や、3.3節の <a href="#s3-3-import-statements">インポート文</a> など）</li>
</ol>
<p>複数の連続した空行を入れて良いが、必須でも推奨でもない。</p>
<h4 id="s4-6-2-horizontal-whitespace">4.6.2 水平の空白</h4>
<p>言語かあるいは他のスタイルルールの求めを超え、リテラル、コメント、Javadoc以外で単一のASCII空白は以下の場所 <strong>のみ</strong> において使って良い。</p>
<ol>
<li>予約語（ <code>if, for , catch</code> ）とその行での開始小括弧 ( <code>(</code> )の間。</li>
<li>予約語（ <code>else, catch</code> ）とその行での前に来る終了中括弧( <code>}</code> )との間。</li>
<li>開始中括弧( <code>{</code> )の前すべて。ただし以下の2個の例外を除く
<ul>
<li>@SomeAnnotation({a, b}) (空白は使わない。)</li>
<li><code>String[][] x = {{"foo"}};</code> ( <code>{{</code> の中に空白は不要。項目8を参照)</li>
</ul></li>
<li>すべての二項あるいは三項演算子の両側。また、以下の様な演算子ライクなシンボルにも適用する。
<ul>
<li>連続する型パラメータ間のアンパサンド。 <code><T extends Foo & Bar></code></li>
<li>複数の例外を処理するcatchブロックでのパイプ。 <code>catch (FooException | BarException e)</code></li>
<li>拡張for文(“foreach”) でのコロン。 ( <code>:</code> )</li>
<li>ラムダ式での矢印。@(String str) →; str.length()@</li>
</ul></li>
<li>以下は除外する。
<ul>
<li><code>Object::toString</code> と書かれるような、メソッド参照でのコロン２個。</li>
<li><code>object.toString</code> と書かれるような、ドット演算子。</li>
</ul></li>
<li><code>, : ;</code> あるいはキャストの閉じ括弧 （ <code>)</code> ） の後ろ。</li>
<li>行末コメントを開始するスラッシュ２個（ <code>//</code> ）の両側。ここでは複数の空白が許されるが必須ではない。</li>
<li>型と変数の宣言の間。 <code>List<String> list</code></li>
<li>任意で、配列初期化子の両括弧の中。
<ul>
<li><code>new int[] {5, 6}</code> と <code>new int[] { 5, 6 }</code> は両方有効。</li>
</ul></li>
</ol>
<blockquote>
<p>注意：このルールは行頭行末の空白について要求や禁止をするものと解釈してはならない。内側の空白のみに適用される。</p>
</blockquote>
<h4 id="s4-6-3-horizontal-alignment">4.6.3 水平位置揃え：全く不要</h4>
<p><strong>用語の注釈：</strong> 水平位置揃えとは前行のトークン(変数名、型名)の真下に次行のトークンが来るように、入れるスペース数を調整するやり方のことである。</p>
<p>このやり方は許されるが、Googleスタイルでは <strong>決して要求されない。</strong> すでにこうなっている箇所をそのまま <em>維持</em> することすら必要ない。</p>
<p>これは水平位置揃えをやっている例とやっていない例である。</p>
<pre>
private int x; // これは良い
private Color color; // これも良い
private int x; // 許容される。しかし今後の編集で
private Color color; // 揃えられなくなるかもしれない。
</pre>
<blockquote>
<p><strong>Tip:</strong> カラムの調整は可読性を上げるが将来のメンテナンスで問題になる。一行だけ直したいときを考えてほしい。この変更は以前のきれいな並びをおかしくするだろう。このようなことが <strong>発生しうる。</strong> このことは開発者(多分君)に近くの行を同様になおせと求める。そして修正範囲の拡大を引き起こす。一行の変更が長大な変更となる。最悪意味のない作業になり、良くても変更履歴を汚染し、レビューが遅くなり、マージの衝突がおこるようになる。</p>
</blockquote>
<h3 id="s4-7-grouping-parentheses">4.7 グループ化の括弧 推奨</h3>
<p>追加のグループ化の括弧は作者とレビュアーが括弧なしでもコードは誤解される余地がないと認めるか、コードが読みやすくなる時のみ省くことが出来る。すべての読者がJava演算子の優先度表を覚えていると仮定するのは合理的では <strong>ない。</strong></p>
<h3 id="s4-8-specific-constructs">4.8 各構造物</h3>
<h4 id="s4-8-1-enum-classes">4.8.1 列挙型</h4>
<p>列挙定数値後のカンマの後ろの改行は任意である。追加の空行（大抵はたった一つ）も許可される。<br />
ありうる可能性は、以下のとおり。</p>
<pre>
private enum Answer {
YES {
@Override public String toString() {
return "yes";
}
},
NO,
MAYBE
}
</pre>
<p>定数値にメソッドもドキュメンテーションもない列挙型は必要に応じて配列の初期化と同様に整形してよい。(4.8.3.1 節 配列の初期化 を参照)</p>
<pre>private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }</pre>
<p>列挙型は <em>クラスである</em> のでクラスに対する他のルールが全て適用される。</p>
<h4 id="s4-8-2-variable-declarations">4.8.2 変数宣言</h4>
<h5>4.8.2.1 宣言ごとに一個の変数</h5>
<p>フィールドでもローカル変数でも変数宣言は一個だけの変数を宣言する。 <code>int a, b;</code> のような宣言は使わない。</p>
<p>例外： 複数の変数宣言をすることは、forループのヘッダーであれば実施して良い。</p>
<h5>4.8.2.2 必要なときに宣言する</h5>
<p>ローカル変数はそれを含むブロックやブロック様の構造物の先頭で慣習的に宣言されては <em>ならない。</em> 代わりに、ローカル変数はそのスコープを最小化するために(合理的な範囲で)最初に使う場所の近くで宣言される。ローカル変数宣言は通常は初期化がされるか、あるいは宣言されてすぐに初期化される。</p>
<h4 id="s4-8-3-arrays">4.8.3 配列</h4>
<h5 id="s4-8-3-1-array-initializers">4.8.3.1 配列の初期化：ブロック様で良い</h5>
<p>配列の初期化はあたかも「ブロック様構造物」のようにやって良い。例えば以下の例はすべて有効である。網羅的なリストでは無い。</p>
<pre>
new int[] { new int[] {
0, 1, 2, 3 0,
} 1,
2,
new int[] { 3,
0, 1, }
2, 3
} new int[]
{0, 1, 2, 3}
</pre>
<h5>4.8.3.2 Cのような配列宣言は禁止</h5>
<p>角括弧は <em>型</em> の一部を構成するが、変数はそうではない。 <code>String[] args</code> は良い。 <code>String args[]</code> はダメ。</p>
<h4 id="s4-8-4-switch">4.8.4 スイッチ文</h4>
<strong>用語についての注釈</strong> スイッチブロックの括弧の内側は一個以上の文グループである。それぞれの文グループは一個以上のスイッチラベル（ <code>case FOO:</code> でも <code>default:</code> であっても）とそれに続く一個以上の文であるか、あるいは最後の文グループの場合は0個以上の文である。
<h5>4.8.4.1 インデンテーション</h5>
<p>他のブロックと同様に、スイッチブロックは空白2個でインデントされる。</p>
<p>スイッチラベルの後に改行が入り、まさにブロックが開始したかのようにインデントレベルは2上がる。次のスイッチラベルではブロックが終わったかのように以前のインデンテーションレベルに戻る。</p>
<h5>4.8.4.2 フォールスルーにはコメントを入れる</h5>
<p>スイッチブロック内では、各ステートメントグループは突然処理が終了する（ <code>break</code> か <code>continue</code> か <code>return</code> か例外のスロー）か、実行が次のステートメントグループに進むようなコメントが付けられるかのどちらかだけである。フォールスルーということを示すコメントも効果的である。 （典型的には <code>// fall through</code> ）この特別なコメントは、最後のステートメントグループには必要ない。</p>
<p>例えば：</p>
<pre>
switch (input) {
case 1:
case 2:
prepareOneOrTwo();
// fall through
case 3:
handleOneTwoOrThree();
break;
default:
handleLargeNumber(input);
}
</pre>
<p>注意： <code>case 1</code> の後にコメントは必要ない。ステートメントグループの終わりのみに必要である。</p>
<h5>4.8.4.3 default 節は必要</h5>
<p>各スイッチ文はたとえコードがない場合でも <code>default</code> ステートメントグループが必須である。</p>
<p>例外：enum型でのswitch文は、その型の全てのあり得る値を明示的に含めているならば、@default@ ステートメントグループを省略して良い。これによりIDEや静的コード分析ツールが何らかの値が漏れていることについて警告を発することが出来るようになる。</p>
<h4 id="s4-8-5-annotations">4.8.5 アノテーション</h4>
<p>クラス、メソッド、コンストラクタに付けられるアノテーションは、ドキュメンテーションブロックの直後に配置される。そして、各アノテーションは１行に１個設定される。<br />
これらの改行は行折り返し(4.5 節 <a href="#s4-5-line-wrapping">行折り返し</a> )に従わない。それ故、インデンテーションレベルも上がらない。例えば：</p>
<pre>
@Override
@Nullable
public String getNameIfPresent() { ... }
</pre>
<p><strong>例外：</strong> 単一のパラメータ無しのアノテーションの場合はシグネチャー行の先頭に現れて良い。例えば：</p>
<pre>
@Override public int hashCode() { ... }
</pre>
<p>フィールドへのアノテーションもドキュメンテーションブロックの直後に現れる。しかしこの場合、複数のアノテーション(パラメータが付きの可能性もある)が同じ行に現れても良い。例えば：</p>
<pre>
@Partial @Mock DataLoader loader;
</pre>
<p>パラメータやローカル変数や型についてのアノテーションには特にルールはありません。</p>
<h4 id="s4-8-6-comments">4.8.6 コメント</h4>
<p>この節では実装コメントについて扱う。Javadocについては7節 Javadoc にて個別に扱われる。</p>
<p>すべての改行の前には任意で空白が入り実装コメントが続く。そのようなコメントは行を非空白にします。</p>
<h5>4.8.6.1 ブロックコメントスタイル</h5>
<p>ブロックコメントは周りのコードと同じレベルにインデントされる。 <code>/* ... */</code> でも <code>//...</code> でも同じである。複数行 <code>/* ... */</code> コメントについては <code>*</code> の位置を前の行の <code>*</code> と同じに揃えなくてはならない。</p>
<pre>
/*
* これは // これも /* こんなかたち
* 良い // 良い * であっても良い。 */
*/
</pre>
<p>コメントはアスタリスクや他の文字で描かれた箱で囲わない。</p>
<blockquote>
<p><strong>Tip:</strong> 複数行コメントを書く際必要に応じ自動フォーマット機能で行折り返ししたい場合は <code>/* ... */</code> スタイルを使うと良い。多くのフォーマッタは <code>// ...</code> スタイルのコメントの改行を直さない。</p>
</blockquote>
<h4 id="s4-8-7-modifiers">4.8.7 修飾子</h4>
<p>クラスやメンバの修飾子が出現する場合、Java言語仕様が推奨する順序で出現しなくてはならない。</p>
<pre>
public protected private abstract default static final transient volatile synchronized native strictfp
</pre>
<h4 id="s4-8-8-numeric-literals">4.8.8 数値リテラル</h4>
<p><code>long</code> 型の数値リテラルは大文字の <code>L</code> を末尾に使う。小文字は使わない。数値 <code>1</code> との混乱を避ける。例えば <code>3000000000l</code> ではなく <code>3000000000L</code> を使う。</p>
<h2 id="s5-naming">5 命名</h2>
<h3 id="s5-1-identifier-names">5.1 すべての識別子への共通ルール</h3>
<p>識別子はASCII文字、数字のみを使う。また後述するいくつかの場合ではアンダースコアも使う。それゆえ、有効な識別子名は正規表現 <code>\w+</code> にマッチする。</p>
<p>(訳注:5.2.4の <a href="#s5-2-4-constant-names">定数名</a> の場合と、5.2.3の <a href="#s5-2-3-method-names">メソッド名</a> でのUnitのテストメソッド名の場合)</p>
<p>Googleスタイルでは、 <code>name_</code> 、 <code>mName</code> 、 <code>s_name</code> や <code>kName</code> といったような特別な接尾辞・接頭辞は <em>使わない。</em></p>
<h3 id="s5-2-specific-identifier-names">5.2 識別子の種類ごとのルール</h3>
<h4 id="s5-2-1-package-names">5.2.1 パッケージ名</h4>
<p>パッケージ名はすべて小文字で連続する単語をそのまま繋げる。アンダースコアは使わない。例えば、 <code>com.example.deepspace</code> であって、 <code>com.example.deepSpace</code> や <code>com.example.deep_space</code> は使わない。</p>
<h4 id="s5-2-2-class-names">5.2.2 クラス名</h4>
<p>クラス名は大文字キャメルケース(UpperCamelCase)で命名する。</p>
<p>クラス名は大抵名詞か名詞句である。例えば、 <code>Character</code> や、 <code>ImmutableList</code> である。インターフェース名も名詞か名詞句である。（例えば <code>List</code> である。）しかし、場合によっては形容詞や形容詞句になる。（例えば、 <code>Readable</code> である。）</p>
<p>アノテーション型に対する特定のルールや確立した規約はない。</p>
<p>テストクラスはテスト対象クラス名で始まり、 <code>Test</code> で終わるよう命名される。例えば <code>HashTest</code> や、 <code>HashIntegrationTest</code> である。</p>
<h4 id="s5-2-3-method-names">5.2.3 メソッド名</h4>
<p>メソッド名は、小文字キャメルケース(lowerCamelCase)で命名される。</p>
<p>メソッド名は大抵動詞か動詞句である。例えば、 <code>sendMessage</code> や <code>stop</code> である。</p>
<p>アンダースコアはJUnitのメソッド名において、名前の論理的コンポーネント名（lowerCamelCaseで書かれる）を分離するために使ってよい。典型的なパターンは <code>test<MethodUnderTest>_<state></code> で、例えば <code>testPop_emptyStack</code> である。テストメソッドを命名する正しい唯一の方法はない。</p>
<h4 id="s5-2-4-constant-names">5.2.4 定数名</h4>
<p>定数は コンスタントケース(CONSTANT_CASE)で命名する。すべて大文字で、各単語を１個のアンダースコアで区切る。しかし定数とは正確には何だろうか。</p>
<p>定数とは、その内容が不変であってそのメソッドは検知可能な副作用を持たないような <code>static final</code> なフィールドである。<br />
例えば、プリミティブ型、String、不変な型、不変な型の不変なコレクションである。<br />
もしインスタンスの観測可能な状態が変化できるなら、それは定数ではない。<br />
単に絶対にオブジェクトを変更しないことを意図するだけでは大抵は不十分である。</p>
<p>例：</p>
<pre>
// 定数である
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final ImmutableMap<String, Integer> AGES = ImmutableMap.of("Ed", 35, "Ann", 32);
static final Joiner COMMA_JOINER = Joiner.on(','); // Joiner は不変であるので。
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }
// 定数でない
static String nonFinal = "non-final";
final String nonStatic = "non-static";
static final Set<String> mutableCollection = new HashSet<String>();
static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);
static final ImmutableMap<String, SomeMutableType> mutableValues =
ImmutableMap.of("Ed", mutableInstance, "Ann", mutableInstance2);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};
</pre>
<p>これらの名前は大抵名詞か名詞句である。</p>
<h4 id="s5-2-5-non-constant-field-names">5.2.5 定数でないフィールド名</h4>
<p>定数でないフィールド名（staticであってもなくても）は小文字キャメルケース(lowerCamelCase)で命名される。</p>
<p>これらの名前は大抵名詞か名詞句である。例えば <code>computedValues</code> や <code>index</code> である。</p>
<h4 id="s5-2-6-parameter-names">5.2.6 パラメータ名</h4>
<p>パラメータ名は小文字キャメルケース(lowerCamelCase)で命名される。</p>
<p>一文字のパラメータ名はpublic なメソッドでは避けるべきである。</p>
<h4 id="s5-2-7-local-variable-names">5.2.7 ローカル変数名</h4>
<p>ローカル変数名は小文字キャメルケース(lowerCamelCase)で命名される。</p>
<p><code>final</code> で不変であってもローカル変数は定数とは見なされないので定数として命名されるのは避けるべきである。</p>
<h4 id="s5-2-8-type-variable-names">5.2.8 型変数名</h4>
<p>型変数名は以下の２つのやり方のうちいずれかで命名される。</p>
<ul>
<li>一つの大文字アルファベット。それに１個の数字が続いて良い。例： <code>E, T, X, T2</code></li>
<li>クラスの命名（5.2.2節 <a href="#s5-2-2-class-names">クラス名</a> ）の後ろに、大文字Tを付加する。例： <code>RequestT, FooBarT</code></li>
</ul>
<h3 id="s5-3-camel-case">5.3 キャメルケースの定義</h3>
<p>時として、"IPv6"や、"iOS"のような頭字語や見慣れない形があるように、英語のフレーズをキャメルケースに変換する合理的な方法は複数ある。正確さを維持するため、Google Styleでは以下のような（ほぼ）決定的な手順を定義する。</p>
<p>名前の通常の形から始めて、</p>
<ol>
<li>言葉を素のASCIIに変換し、アポストロフィを除去する。例えば、"Müller’s algorithm" は “Muellers algorithm”に変換される。</li>
<li>これをスペースや残っている句読点（大抵はハイフン）で分離し、単語に分割する。
<ul>
<li>推奨：もしもある単語が通常の利用において既に慣習的にキャメルケースの形をとっているならばそれも分解する。（例：「AdWords」 を 「ad words」にする。）「iOS」のような単語そのものは真にキャメルケースになっておらず、どんな規約にも当てはまらないのでこの推奨も適用されないないことに注意すること。</li>
</ul></li>
<li>（頭字語を含めて）すべてを小文字にする。そして以下の語の最初の文字を大文字にする。
<ul>
<li>それぞれの単語。この場合大文字キャメルケースとなる。</li>
<li>最初の単語を除いたそれぞれの単語。この場合小文字キャメルケースになる。</li>
</ul></li>
<li>最後に、すべての単語を１個の識別子として連結する。</li>
</ol>
<p>元々の単語の大文字小文字はほとんど全て無視される。例えば、</p>
<table>
<tr>
<td>元々の形</td>
<td>正しい変換例</td>
<td>誤った変換例</td>
</tr>
<tr>
<td>“<span class="caps">XML</span> <span class="caps">HTTP</span> request”</td>
<td>XmlHttpRequest</td>
<td>XMLHTTPRequest</td>
</tr>
<tr>
<td>“new customer ID”</td>
<td>newCustomerId</td>
<td>newCustomerID</td>
</tr>
<tr>
<td>“inner stopwatch”</td>
<td>innerStopwatch</td>
<td>innerStopWatch</td>
</tr>
<tr>
<td>“supports IPv6 on iOS?”</td>
<td>supportsIpv6OnIos</td>
<td>supportsIPv6OnIOS</td>
</tr>
<tr>
<td>“YouTube importer”</td>
<td>YouTubeImporter <br> YoutubeImporter <sup class="footnote" id="fnr2"><a href="#fn2">2</a></sup></td>
<td></td>
</tr>
</table>
<p class="footnote" id="fn2"><a href="#fnr2"><sup>2</sup></a> やってよいが推奨されない。</p>
<blockquote>
<p><strong>注釈：</strong> いくつかの単語は英語として曖昧にハイフン付けされている。例えば、"nonempty" と “non-empty” はどちらも正しい。それゆえ同様に <code>checkNonempty</code> と <code>checkNonEmpty</code> というメソッド名はどちらも正しい。</p>
</blockquote>
<h2 id="s6-programming-practices">6 プログラミングの実践</h2>
<h3 id="s6-1-override-annotation">6.1 @Override：常に使う</h3>
<p>適用可能ならば、メソッドには @Overrideアノテーションを付与する。これは親クラスのメソッドをオーバーライドするクラスのメソッドや、インターフェースのメソッドを実装するクラスのメソッドや、親インターフェースのメソッドを再定義する子インターフェースのメソッドにもあてはまる。</p>
<p><strong>例外：</strong> @Override は親メソッドが@Deprecated の場合書かなくて良い。</p>
<h3 id="s6-2-caught-exceptions">6.2 キャッチされた例外：無視しない</h3>
<p>以下の例を除き、キャッチした例外についてなにも対応しないことが正しいことはめったにない。（典型的な対応はログを取るか、ありえない場合ならば <code>AssertionError</code> として再スローすることである。）</p>
<p>キャッチ節でなにもしないことが本当に適切であるならば、それを正当化する理由をコメントで説明する。</p>
<pre>
try {
int i = Integer.parseInt(response);
return handleNumericResponse(i);
} catch (NumberFormatException ok) {
// 数字ではない。正常であるので続行する。
}
return handleTextResponse(response);
</pre>
<p><strong>例外：</strong> テストにおいて、キャッチされた例外が、 <code>expected</code> と命名されているあるいは始まる名前である場合は、コメントなしで無視してよい。以下の例はテスト対象のコードが期待した型の例外をスローすることを確認するためのよくあるイディオムであり、コメントは不要である。</p>
<pre>
try {
emptyStack.pop();
fail();
} catch (NoSuchElementException expected) {
}
</pre>
<h3 id="s6-3-static-members">6.3 staticなメンバー：クラスを使って修飾する</h3>
<p>staticなメンバーを修飾する必要がある場合はクラス名を使う。そのクラスの変数や式経由で使ってはならない。</p>
<pre>
Foo aFoo = ...;
Foo.aStaticMethod(); // 良い
aFoo.aStaticMethod(); // 悪い
somethingThatYieldsAFoo().aStaticMethod(); // とても悪い
</pre>
<h3 id="s6-4-finalizers">6.4 ファイナライザ：使わない</h3>
<p><code>Object</code> クラスの <code>finalize()</code> メソッドを使うケースは非常に稀である。</p>
<blockquote>
<p><strong>Tip:</strong> これをやってはならない。絶対的に必要ならば、まず <a href="http://books.google.co.jp/books?id=ka2VUBqHiWkC">Effective JavaのItem7</a> 「ファイナライザを避ける」を必ず熟読しなくてはならない。そしてこれをやってはならない。</p>
</blockquote>
<h2 id="s7-javadoc">7 Javadoc</h2>
<h3 id="s7-1-javadoc-formatting">7.1 フォーマット</h3>
<h4 id="s7-1-1-javadoc-multi-line">7.1.1 一般的なフォーマット</h4>
<p>Javadocブロックの基本的なフォーマットはこの例で表される。</p>
<pre>
/**
* 複数行のJavadocテキストはここに書かれる。
* 普通に改行される。
*/
public int method(String p1) { ... }
</pre>
<p>一行の例はこうである。</p>
<pre>
/** 特に短いJavadoc */
</pre>
<p>基本的な形は常に適用される。 一行の形はJavadocブロック全体（コメントマーカを含む）が１行で書ける場合のみ置き換えることができる。これは@returnタグのようなブロックタグが存在しない場合のみ適用可能であることに注意すること。</p>
<h4 id="s7-1-2-javadoc-paragraphs">7.1.2 段落</h4>
<p>一つの空行つまり先頭のアスタリスク(*)のみの行が段落と段落の間に挿入される。もしブロックタググループがあるならばその前にも挿入される。最初以外のすべての段落には、最初の単語の前に空白無しで <code><p></code> が入れられる。</p>
<h4 id="s7-1-3-javadoc-at-clauses">7.1.3 ブロックタグ <sup class="footnote" id="fnr3"><a href="#fn3">3</a></sup></h4>
<p>全ての標準の&ブロックタグで& で、実際に利用されるものは @param, @return, @throws, @deprecatedの順で現れる。これらの４つには記述が必ず存在しなくてはならない。ブロックタグが１行コメントに収まらない場合、２行目以降は @ の位置からスペース４個以上インデントされる。</p>
<p class="footnote" id="fn3"><a href="#fnr3"><sup>3</sup></a> 訳注：本家のJavadocの文書 でいうところの 「Javadocタグ」のこと。参照 <a href="http://docs.oracle.com/javase/jp/8/docs/technotes/tools/windows/javadoc.html#CHDBEFIF">Javadoc タグ</a></p>
<h3 id="s7-2-summary-fragment">7.2 要約の記述</h3>
<p>全てのJavadocブロックは簡単な <strong>要約の記述</strong> から始まる。この記述はとても重要である。なぜならクラスやメソッドの索引のような特別な場所に現れる唯一のテキストだからである。</p>
<p>この記述は小さな断片の形である。つまり名詞句か動詞句であって、完全な文であってはならない。「このクラス {@code Foo} は…」とか「このメソッドは…を返す。」で始まってはならないし、「結果を保存しなさい。」という命令形であってもならない。他方においてこの断片はあたかも文であるかのように大文字に変えられたり、句読点が付けられる。</p>
<blockquote>
<p><strong>Tip:</strong> /** @return 顧客ID */ といった簡単なJavadocを書くことはよくある間違いである。これは間違いで正しくは以下のように直されるべきである。 <code>/** 顧客IDを返す。 */</code></p>
</blockquote>
<h3 id="s7-3-javadoc-where-required">7.3 Javadocが使われる場所</h3>
<p>少なくとも、Javadocは <code>public</code> なクラスとそのクラスの <code>public</code> 、 <code>protected</code> なメンバーに書かれる。但し以下の例外がある。</p>
<p>追加のJavadocコメントがある場合がある。7.3.4節 不要なJavadoc にて解説される。</p>
<h4 id="s7-3-1-javadoc-exception-self-explanatory">7.3.1 例外：自己叙述的なメソッド</h4>
<p>Javadocは <code>getFoo</code> のような簡単で明確なメソッドの場合は必須ではない。つまり、「fooを返す」以外の意味ある情報が本当に無い場合である。</p>
<blockquote>
<p><strong>Tip: 重要：</strong> 典型的な読者が知りたがるような関連情報を省略することを正当化するためにこの例外を引用するのは適切ではない。例えば、「getCanonicalName」というメソッドにおいて典型的な読者が「canonical name」という語の意味を知らないかもしれない場合、（単に <code>/** canonical name を返す。 */</code> と書くだけであるという理由で）省略してはならない。</p>
</blockquote>
<h4 id="s7-3-2-javadoc-exception-overrides">7.3.2 例外：オーバーライドするメソッド</h4>
<p>親クラスのメソッドをオーバーライドするメソッドについてはJavadocは必須ではない。</p>
<h4 id="s7-3-4-javadoc-exception-overrides">7.3.4 必須ではないJavadoc</h4>
<p>訳注：節番号が飛んでいるが、原文に従う。</p>
<p>他のクラスとメンバーにもJavadocは必要に応じて書かれる。</p>
<p>クラスやメンバの全体の目的を記述するのに実装コメントが使われているならば、そのコメントは代わりにJavadocで書かれる。（ <code>/**</code> ）</p>
<p>必須ではないJavadocは7.1.2, 7.1.3, 7.2 節のフォーマット規則に従うことがもちろん推奨であるが、必ずしも必要ではない。</p>
</body>
</html>