-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathlispguide.xml
executable file
·5450 lines (5366 loc) · 331 KB
/
lispguide.xml
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
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
<GUIDE title="Google Common Lisp スタイルガイド 日本語訳">
<div align="center">
これは<a href="https://github.com/google/styleguide/blob/gh-pages/lispguide.xml">Google Common Lisp Style Guide (1.28)</a>の日本語訳です。<br/>
オリジナルと同様、<a href="http://creativecommons.org/licenses/by/3.0/">CC-By 3.0 License</a>で配布します。<br/>
最終更新: 2018-01-17
</div>
<p align="right">
Revision 1.28
</p>
<address>
Robert Brown
</address>
<address>
<a HREF="mailto:[email protected]">François-René Rideau</a>
</address>
<address>
Dan Weinrebに捧ぐ
</address>
<p align="right">
日本語訳:現在進行中(求共訳者)
</p>
<!-- 皆さんお名前はご自由に直してください -g000001
順番は大体の量に比例
-->
<address>
TOYOZUMIKouichi
</address>
<address>
κeen
</address>
<address>
g000001
</address>
<address>
@guicho271828
</address>
<address>
kealthou
</address>
<address>
佐野匡俊
</address>
<address>
Takashi Kato
</address>
<address>
@ponkore
</address>
<address>
(訳文アドバイスを頂いた皆さん: @nfunato, @omasanori, etc)
</address>
<p align="center">
<cite>「パターンとは『言語の表現力を超えてしまった』ということだ」</cite> — Rich Hickey
<!-- Patterns mean "I have run out of language." -->
</p>
<OVERVIEW>
<CATEGORY title="重要事項">
<STYLEPOINT title="詳細情報の表示">
<SUMMARY>
<!-- This style guide contains many details that are initially
hidden from view. They are marked by the triangle icon,
which you see here on your left. Click it now. You should
see "Hooray" appear below. -->
このスタイルガイドには詳細情報がたくさん盛り込まれていますが、最
初は表示されていません。左端にある矢印ボタンをクリックしてみてく
ださい。 「ヒャッホー!」と表示されるはずです。
</SUMMARY>
<BODY>
<p>
<!-- Hooray! Now you know you can expand points to get more
details. Alternatively, there's an "expand all" at the
top of this document.-->
ヒャッホー! このように矢印ボタンをクリックすると詳細情報が表示されます。
このドキュメントの先頭にある大きな矢印ボタンをクリックしても構いません。
そうすれば、すべての詳細情報が表示されます。訳注は[]で囲んで表わします。
<!-- とりあえず []で表記することにしてみました。-->
</p>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="背景">
<p>
<!--
Common Lisp is a powerful multiparadigm programming language.
With great power comes great responsibility.
-->
Common Lispは強力なマルチパラダイム言語です。
強力さには責任が伴います。
</p>
<p>
<!--
This guide recommends formatting and stylistic choices
designed to make your code easier for other people to understand.
-->
このガイドはあなたのコードを他人にとって理解しやすくするよう設計された書式とスタイルの選択を奨励します。
<!--
For those internal applications and free software libraries that
we develop at Google,
you should keep within these guidelines when making changes.
Note however that each project has its own rules and customs
that complement or override these general guidelines;
the speed-oriented QPX low fare search engine notably
has a very different style and feel from the QRes reservation system.
-->
Googleで開発される内製アプリケーション及びフリーソフトに変更を行う際は、
このガイドラインに沿うべきです。
しかし、それぞれのプロジェクトには独自のルールや習慣があり、
それらはこれらの一般向けガイドラインを補足もしくは上書きすることに気をつけてください;
速度重視の低コスト検索エンジンQPXはとりわけ
QRes予約システムとはとても異なるスタイルとセンスで作られています。
</p>
<p>
<!--
If you're writing Common Lisp code outside Google,
we invite you to consider these guidelines.
-->
もしGoogle以外でCommon Lispのコードを書くのであれば、
これらガイドラインの項目について検討されることをお勧めします。
<!-- You may find some of them useful -->
<!-- where they don't conflict with other priorities you have. -->
<!-- We welcome remarks and constructive feedback -->
<!-- on how to improve our guide, and -->
<!-- on what alternate styles work for you and why. -->
あなたの他の優先事項と競合しない範囲でこれらの中に有用なものがあるかもしれません。
我々のガイドへの改善案と、あなたの下で上手くいっているスタイルとその理由について、建設的なフィードバックを歓迎します。
</p>
<p>
<!--
This guide is not a Common Lisp tutorial.
For basic information about the language, please consult
<a HREF="http://www.gigamonkeys.com/book/">Practical Common Lisp</a>.
For a language reference, please consult the
<a HREF="http://www.lispworks.com/documentation/HyperSpec/Front/index.htm">Common Lisp HyperSpec</a>.
For more detailed style guidance, take (with a pinch of salt)
a look at Peter Norvig and Kent Pitman's
<a HREF="http://norvig.com/luv-slides.ps">style guide</a>.
-->
このガイドはCommon Lispのチュートリアルではありません。
言語についての基礎的な情報については
<a HREF="http://www.gigamonkeys.com/book/">Practical Common Lisp</a>を参照して下さい。
言語リファレンスとしては
<a HREF="http://www.lispworks.com/documentation/HyperSpec/Front/index.htm">Common Lisp HyperSpec</a>
を参照して下さい。より詳細なスタイルガイドについてはPeter Norvig とKent Pitmanの
<a HREF="http://norvig.com/luv-slides.ps">style guide</a>を(鵜呑みにするのではなしに)参照して下さい。
</p>
</CATEGORY>
</OVERVIEW>
<CATEGORY title="メタガイド"><!-- Meta-Guide -->
<STYLEPOINT title="重要度による語尾表現の違い">
<SUMMARY>
<!--
Each guideline's level of importance is indicated
by use of the following keywords and phrases, adapted from
<a href="https://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>.
-->
それぞれのガイドラインの重要度のレベルは
<a href="https://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>から
採用した以下の語句で示します。
</SUMMARY>
<BODY>
<table>
<tr>
<th valign="top">しなければならない:MUST</th>
<td>
<p>
<!--
This word, or the terms "REQUIRED" or "SHALL",
means that the guideline is an absolute requirement.
You must ask permission to violate a MUST.
-->
「しなければならない:"MUST"」「要求される:"REQUIRED"」「するものとする:"SHALL"」といった用語は、
そのガイドラインが絶対的な要求であることを意味します。
「しなければならない」ことに違反する場合は許可を求めなければなりません。
</p>
</td>
</tr>
<tr>
<th valign="top">してはならない:MUST NOT</th>
<td>
<p>
<!--
This phrase, or the phrase "SHALL NOT",
means that the guideline is an absolute prohibition.
You must ask permission to violate a MUST NOT.
-->
「してはならない:"MUST NOT"」や「しないものとする:"SHALL NOT"」といった句は、
そのガイドラインが絶対的な禁止であることを意味します。
「してはならない」ことに違反する場合は許可を求めなければなりません。
</p>
</td>
</tr>
<tr>
<th valign="top">すべき:SHOULD</th>
<td>
<p>
<!--
This word, or the adjective "RECOMMENDED", means that
there may exist valid reasons in particular circumstances
to ignore the demands of the guideline, but
the full implications must be understood and carefully weighed
before choosing a different course.
You must ask forgiveness for violating a SHOULD.
-->
語「すべき:"SHOULD"」や形容詞「推奨される:"RECOMMENDED"」は、
ある状況ではガイドの要求を無視する適切な理由があるかもしれないことを意味しますが、
他のやり方を選択する前にガイドの含意全てを理解し入念に比較しなければなりません。
「すべき」ことに違反する場合承認を求めなければなりません。
</p>
</td>
</tr>
<tr>
<th valign="top">すべきでない:SHOULD NOT</th>
<td>
<p>
<!--
This phrase, or the phrase "NOT RECOMMENDED", means that
there may exist valid reasons in particular circumstances
to ignore the prohibitions of this guideline, but
the full implications should be understood and carefully weighed
before choosing a different course.
You must ask forgiveness for violating a SHOULD NOT.
-->
句「すべきでない:"SHOULD NOT"」と句「推奨されない:"NOT RECOMMENDED"」は、
ある状況ではガイドの禁止を無視する適切な理由があるかもしれないことを意味しますが、
他のやり方を選択する前にガイドの含意全てを理解し入念に比較すべきです。
「すべきでない」ことに違反する場合承認を求めなければなりません。
</p>
</td>
</tr>
<tr>
<th valign="top">MAY</th>
<td>
<p>
<!--
This word, or the adjective "OPTIONAL",
means that an item is truly optional.
-->
語「しても良い:"MAY"」や形容詞「任意に:"OPTIONAL"」はその項目は完全に任意であることを意味します。
</p>
</td>
</tr>
</table>
<p>
<!--
Unlike RFCs, we don't capitalize every instance of one of the above
keywords when it is used.
-->
RFCとは異なり、上記キーワードの利用全てを大文字で表記するわけではありません。
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="許可と承認"><!-- Permission and Forgiveness -->
<SUMMARY>
<!--
There are cases where transgression of some of these rules
is useful or even necessary.
In some cases, you must seek permission or obtain forgiveness
from the proper people.
-->
ガイドで示すルールに対する違反が有効であったり必要でさえあるケースがあります。
いくつかのケースでは、適切な人達からの許可や承認を求めなければなりません。
</SUMMARY>
<BODY>
<p>
<!--Permission comes from the owners of your project.-->
許可はあなたのプロジェクトの所有者から得ます。
</p>
<p>
<!--
Forgiveness is requested in a comment near the point of guideline violation,
and is granted by your code reviewer.
The original comment should be signed by you, and
the reviewer should add a signed approval to the comment at review time.
-->
承認はガイドライン違反をした箇所の近くのコメントの中でリクエストされ、レビューアによって承諾されます。
オリジナルのコメントはあなたの名前で署名すべきで、レビューアは
レビュー時に署名した承認を追記すべきです。
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="慣例"><!-- Conventions -->
<SUMMARY>
<!-- You MUST follow conventions. They are not optional. -->
慣例には必ず従わなくてはなりません。これは任意の選択事項ではありません。
</SUMMARY>
<BODY>
<p>
<!-- Some of these guidelines are motivated by universal principles of good programming. -->
ガイドラインの中には、よいプログラミングの普遍的な原則に基づいているものがあります。
<!-- Some guidelines are motivated by technical peculiarities of Common Lisp. -->
Common Lispの技術的な特性に基づいているものもあります。
<!-- Some guidelines were once motivated by a technical reason, -->
<!-- but the guideline remained after the reason subsided. -->
かつては技術的な理由に基づいていましたが、その理由がなくなった後もそのまま残ったものもあります。
<!-- Some guidelines, such those about as comments and indentation, -->
<!-- are based purely on convention, rather than on clear technical merit. -->
コメントや字下げに関するものなど、明確な技術的利点というよりはただの慣例に基づいているものもあります。
<!-- Whatever the case may be, you must still follow these guidelines, -->
<!-- as well as other conventional guidelines -->
<!-- that have not been formalized in this document. -->
どのケースであれ、この文書で形式化しなかった他の慣例的ガイドラインはもちろんのこと、
それらのガイドラインには従わなければなりません。
</p>
<p>
<!--
You MUST follow conventions.
They are important for readability.
When conventions are followed by default,
violations of the convention are a signal
that something notable is happening and deserves attention.
When conventions are systematically violated,
violations of the convention are a distracting noise
that needs to be ignored.
-->
慣例には必ず従わなければなりません。慣例は可読性を向上させます。<!-- 直訳だと日本語がおかしくなるので意訳。-->
慣例にデフォルトで従っていれば、慣例違反を見つけた際に、そこで注目に値する何かが起きていて、注意が必要なシグナルだと分かります。
慣例を体系的に違反してしまったら、慣例違反は無視しなければならない邪魔なノイズになります。<!-- 訳微妙 -->
</p>
<p>
<!--
Conventional guidelines <em>are</em> indoctrination.
Their purpose is to make you follow the mores of the community,
so you can more effectively cooperate with existing members.
-->
慣例的ガイドラインとは<em>正に</em>宗教です。
その目的はあなたにコミュニティの教義を信奉させ、より効果的に既存のメンバーと協力できるようにすることです。
<!-- It is still useful to distinguish the parts that are technically motivated -->
<!-- from the parts that are mere conventions, -->
<!-- so you know when best to defy conventions for good effect, -->
<!-- and when not to fall into the pitfalls that the conventions are there to help avoid. -->
とはいえ、技術的に動機づけられている部分と、只の慣例に過ぎない部分を区別することは有益です。良い結果を得るために慣例に逆らうべき時と、慣例に倣い落とし穴に落ちないようにすべき時を区別できるようになります。
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="古いコード"><!-- Old Code -->
<SUMMARY>
<!-- Fix old code as you go. -->
古いコードは都度修正すること。
</SUMMARY>
<BODY>
<p>
<!-- A lot of our code was written before these guidelines existed. -->
我々のコードの多くは、このガイドラインができる以前に書かれました。
<!-- You should fix violations as you encounter them -->
<!-- in the course of your normal coding. -->
普段のコーディングの間に遭遇したガイドライン違反は見つけ次第修正すべきです。
</p>
<p>
<!-- You must not fix violations en masse -->
<!-- without warning other developers and coordinating with them, -->
<!-- so as not to make the merging of large branches -->
<!-- more difficult than it already is. -->
巨大なブランチの統合が今以上に難しくならないよう、
他の開発者に注意を促したり話し合うことなしに違反をひとまとめに修正してはなりません。
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="将来の課題"><!-- Future Topics -->
<SUMMARY>
<!-- There are many topics for additional standardization -->
<!-- not covered by current version of this document, -->
<!-- but deferred to future versions. -->
多くの追加の標準化すべき事柄があり、現在のバージョンのこの文書にはありませんが、将来のバージョンに延期されています。
</SUMMARY>
<BODY>
<ul>
<li>
<!-- File and directory structure -->
ファイルとディレクトリ構造
</li>
<li>
<!-- Packages and modularity -->
パッケージとモジュール性
</li>
<li>
<!-- Threads and locking -->
スレッドとロック
</li>
<li>
<!-- How to add configurable components -->
設定可能な部品の追加方法
</li>
<li>
<!-- CLOS style: initforms, slot and accessor names, etc. -->
CLOSスタイル:初期化方法、スロットおよびアクセサの名前など
</li>
<li>
<!-- Recommendations on max number of slots per class. -->
クラスあたりのスロット数の推奨される最大の数
</li>
<li>
<!-- More concrete examples of good code: -->
より具体的なよいコードの例
<ul>
<li>
<!-- exceptions -->
例外
</li>
<li>
<!-- transactions, with retry -->
トランザクションとリトライ
</li>
<li>
XML
</li>
<li>
<!-- typing -->
型
</li>
<li>
<!-- encapsulation / abstraction -->
カプセル化と抽象化
</li>
<li>
<!-- class and slot names -->
クラスとスロットの名前
</li>
<li>
<!-- etc. -->
など
</li>
</ul>
</li>
<li>
<!-- When (not) to use conditional compilation: -->
条件付コンパイルの(非)使用時：<!-- compilation = コンパイル？ or 編集?-->
<ul>
<li>
<!-- modifying the product -->
プロダクトの修正
</li>
<li>
<!-- conditional debugging/console output/etc. -->
条件付デバッグ、コンソール出力、など
</li>
<li>
<!-- "temporarily" commenting-out blocks of code -->
"一時的な"コードのコメント化
</li>
<li>
<!-- etc. -->
など
</li>
</ul>
</li>
</ul>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="基本的なガイドライン"><!-- General Guidelines -->
<STYLEPOINT title="原則"><!-- Principles -->
<SUMMARY>
<!-- There are some basic principles for team software development -->
<!-- that every developer must keep in mind. -->
ここにはチームでのソフトウェア開発にあたり、全ての開発者が心に留めておかなければならない基本的な原則を記してあります。
<!-- Whenever the detailed guidelines are inadequate, confusing or contradictory, -->
<!-- refer back to these principles for guidance: -->
個別のガイドラインが、不適切な、混乱を引き起こす、または矛盾している場合は、この原則に戻って参考にしてください。
<ul>
<li>
<!--
Every developer's code must be easy for another developer
to read, understand, and modify
— even if the first developer isn't around to explain it.
(This is the "hit by a truck" principle.)
-->
全ての開発者が書いたコードは他の開発者にとって簡単に読めて、理解でき、修正できなければなりません。
例え最初の開発者が近くに居らず説明不可能であっても。([もし主要開発者が]トラックにはねられたらの原理)
<!-- なんのこと？ -->
<!-- http://en.wikipedia.org/wiki/Bus_factor 主要開発者がトラックにはねられて死んだもプロジェクトは続行できなくてはならない的な比喩みたいです: g000001 -->
</li>
<li>
<!--
Everybody's code should look the same.
Ideally, there should be no way to look at lines of code
and recognize it as "Fred's code" by its style.
-->
全ての人のコードは同じに見えるべきです。
理想としては、コードを見て「Fredが書いたな」と判別できるべきではありません。<!-- 単語を全部入れるべき？ -->
</li>
<li>
<!-- Be precise. -->
正確に。
</li>
<li>
<!-- Be concise. -->
無駄なく。
</li>
<li>
<!-- KISS — Keep It Simple, Stupid. -->
KISSの原則を守りましょう。単純にしておけ、この間抜け(Keep It Simple Stupid)。
</li>
<li>
<!-- Use the smallest hammer for the job. -->
牛刀を使って鶏を割くことのないように。
<!-- って書くのが日本語として熟れていると思うのですが、そうすると下の方の「small hammer」をどう処理するかが問題です。TOYOZUMI -->
</li>
<li>
<!-- Use common sense. -->
常識を使います。
</li>
<li>
<!-- Keep related code together. -->
<!-- Minimize the amount of jumping around -->
<!-- someone has to do to understand an area of code. -->
関連するコードは近くに置く。
最小限のコード間ジャンプでコードを理解できるように。
</li>
</ul>
</SUMMARY>
<BODY>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="優先順位"><!-- Priorities -->
<SUMMARY>
<p>
<!-- When making decisions about how to write a given piece of -->
<!-- code, aim for the following -ilities in this priority order: -->
コードをどう書くかということを決定する際に、どんな「~やすさ」に重きを置くかはこの優先順位に従います。
</p>
<ul>
<li>
<!-- Usability by the customer -->
顧客にとっての使いやすさ
</li>
<li>
<!-- Debuggability/Testability -->
デバッグのしやすさ、テストのしやすさ
</li>
<li>
<!-- Readability/Comprehensibility -->
読みやすさ、理解しやすさ
</li>
<li>
<!-- Extensibility/Modifiability -->
拡張のしやすさ、修正のしやすさ
</li>
<li>
<!-- Efficiency (of the Lisp code at runtime) -->
(Lispコードの実行時の)性能の引き出しやすさ
</li>
</ul>
</SUMMARY>
<BODY>
<p>
<!-- Most of these are obvious. -->
ほとんどは明快でしょう。
</p>
<p>
<!-- Usability by the customer means that the system has to do what the -->
<!-- customer requires; it has to handle the customer's transaction -->
<!-- volumes, uptime requirements; etc. -->
顧客にとっての使いやすさとは、システムが顧客の必要とすることをしなければならないということです。
顧客の取引量や稼働時間要求などに応えなければなりません。
</p>
<p>
<!-- For the Lisp efficiency point, -->
<!-- given two options of equivalent complexity, -->
<!-- pick the one that performs better. -->
<!-- (This is often the same as the one that conses less, -->
<!-- i.e. allocates less storage from the heap.) -->
Lispコードの性能については、
二つの選択肢があり、両方が同程度複雑であったなら、性能の良いものを選びます。
(これはしばしば、コンシングの少ない方、という意味と等価です。
つまり、ヒープから割り当てる領域が少なくて済む方、ということです。）
</p>
<p>
<!-- Given two options where one is more complex than the other, -->
<!-- pick the simpler option and revisit the decision only if -->
<!-- profiling shows it to be a performance bottleneck. -->
二つの選択肢があり、片方がもう片方より複雑な場合は、
簡単な方の選択肢を選び、決定を再検討するのはプロファイルによってそれが性能のボトルネックだと分かった時のみにしてください。
</p>
<p>
<!-- However, avoid premature optimization. -->
<!-- Don't add complexity to speed up something that runs rarely, -->
<!-- since in the long run, it matters less whether such code is fast. -->
しかし、時期尚早な最適化は避けます。
コードを複雑にしてまで滅多に走らない部分を高速化しないでください。
長い目で見るとそんなコードが速いかどうかは大して意味がありません。
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="設計"><!-- Architecture -->
<SUMMARY>
<!-- To build code that is robust and maintainable, -->
<!-- it matters a lot how the code is divided into components, -->
<!-- how these components communicate, -->
<!-- how changes propagate as they evolve, -->
<!-- and more importantly -->
<!-- how the programmers who develop these components communicate -->
<!-- as these components evolve. -->
堅牢でメンテナンス性の高いコードを組む際に非常に重要なのが、コードをどのようにコンポーネントに分割するか、どのようにそのコンポーネントが連携するか、コンポーネントの進化するに連れ変更がどう伝播するのか、そしてそれ以上に重要なのは、コンポーネントの進化に合わせその開発者たちがどうコミュニケーションをとるかです。
</SUMMARY>
<BODY>
<p>
<!-- If your work affects other groups, might be reusable across groups, -->
<!-- adds new components, has an impact on other groups -->
<!-- (including QA or Ops), or otherwise isn't purely local, -->
<!-- you must write it up using at least a couple of paragraphs, -->
<!-- and get a design approval from the other parties involved -->
<!-- before starting to write code — or be ready to scratch what you have -->
<!-- when they object. -->
もしあなたの作業が、他にグループに影響を及ぼす、グループの垣根を越えて再利用可能かもしれない、
新しいコンポーネントを追加する、（QAやOpsを含めて）他のグループに影響がある、
あるいは単に局地的なものでないとき、
コードを書き始める前に、それを最低でも2〜3つの段落の文章で詳しく書き上げ、
他の関係者からデザインの承認を得なければなりません。それをしないなら、反対されたときに書いていたコードを捨てる覚悟をしておいてください。
</p>
<p>
<!-- If you don't know or don't care about these issues, -->
<!-- ask someone who does. -->
もしこの点に関して、知らない、気にならないなら、知っている人、気にしている人に尋ねましょう。
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="ライブラリの使用"><!-- Using Libraries -->
<SUMMARY>
<!-- Often, the smallest hammer is to use an existing library. -->
<!-- Or one that doesn't exist yet. -->
<!-- In such cases, you are encouraged to use or develop such a library, -->
<!-- but you must take appropriate precautions. -->
しばしば、鶏を捌くのに最適な包丁<!-- 上記の牛刀に合わせました -->は既存のライプラリを使うことです。
まだそのライブラリは存在していないかも知れません。
そういう場合は、そのようなライブラリの使用か開発が奨励されますが、
適切な備えを講じなければなりません。
</SUMMARY>
<BODY>
<ul>
<li>
<!-- You MUST NOT start a new library -->
<!-- unless you established that none is already available -->
<!-- that can be fixed or completed into becoming what you need. -->
既存品を修正したり未完成品の完成させても、必要とするものにならないと
証明できなければ、新しいライブラリの開発を決して始めてはなりません。
<!-- That's a rule against the NIH syndrome ("Not Invented Here"), -->
<!-- which is particularly strong amongst Lisp hackers. -->
このルールはLispハッカーには重症患者の多い、
NIH("Not Invented Here"ここでつくられていない）症候群に対抗するものです。
</li>
<li>
<!-- Whichever library, old or new, you pick, you MUST get permission -->
<!-- to incorporate third-party code into the code base. -->
選んだライブラリが古いものであれ新しいものであれ、
第三者の作ったコードをコードベースへ組み込むには、
許可を得なくてはなりません。
<!-- You must discuss the use of such library -->
<!-- in the appropriate mailing-list, -->
<!-- and have your code reviewed by people knowledgeable in the domain -->
<!-- and/or the Lisp library ecosystem (if any). -->
そういうライブラリを使用について、適切なメーリングリストで議論し、
またあなたのコードをそのドメインと(もしあれば)Lispライブラリのエコシステムに
詳しい人に査読してもらわなければなりません。
<!-- Please be ready to argue why this particular solution makes sense -->
<!-- as compared to other available libraries. -->
他のライブラリと比較し、なぜこのライブラリでなくてはならないのか、その正当性を主張する準備をしてください。
</li>
<li>
<!-- Some libraries are distributed under licenses not compatible -->
<!-- with the software you're writing, and -->
<!-- must not be considered available for use. -->
ライブラリの中にはあなたが書いているソフトウェアと互換性のないライセンスで
配布されていて、利用できると見做してはならないものがあります。
<!-- Be aware of these issues, or consult with people who are. -->
これらの問題を認識するか、認識している人に相談してください。
</li>
</ul>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Open-Sourcing Code">
<SUMMARY>
<p>
<!-- If you write a general-purpose library, -->
<!-- or modify an existing open-source library, -->
<!-- you are encouraged to publish the result -->
<!-- separate from your main project and then -->
<!-- have your project import it like any other open-source library. -->
汎用ライブラリを書いたり
既存のオープンソースライブラリを修正するときは、
その成果はあなたの本来のプロジェクトから切り離して公開し、
それから改めて他のオープンソースライブラリと同様にあなたのプロジェクトに組み入れる
ことが推奨されます。
</p>
</SUMMARY>
<BODY>
<p>
<!-- Use your judgment to distinguish -->
<!-- general-purpose versus business-specific code, -->
<!-- and open-source the general-purpose parts, -->
<!-- while keeping the business-specific parts a trade secret. -->
汎用コードと業務に固有なコードの違いは自ら見分け、
汎用な部分をオープンソース化し、
業務に固有の部品を企業秘密のままにしてください。
</p>
<p>
<!-- Open-Sourcing code has many advantages, -->
<!-- including being able to leverage third parties for development, -->
<!-- letting the development of features be user-directed, -->
<!-- and keeping you honest with respect to code quality. -->
コードのオープンソース化には、
開発に第三者の力を活用できる、
機能開発がユーザー主導になる、
コードの品質に関して誤魔化しが効かなくなるなど、
多くの利点があります。
<!-- Whatever code you write, you will have to maintain anyway, -->
<!-- and make sure its quality is high enough to sustain use in production. -->
どんなコードを書いたとしても、どのみち保守しなければなりませんし、
<!-- itが抜けているものとします -->
確実に業務の使用に耐えるような高品質を維持するようにしてください。
<!-- There should therefore be no additional burden to Open-Sourcing, -->
<!-- even of code that (at least initially) -->
<!-- is not directly usable by third parties. -->
故に（少なくとも当初は）第三者にとって直接使い道のないコードであっても、
オープンソース化でついでに掛かる負担はないはずです。
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="開発手順"><!-- Development Process -->
<SUMMARY>
<!-- Development process is outside the scope of this document. -->
開発手順は、このドキュメントの対象範囲外です。
<!-- However, developers should remember at least these bits: -->
<!-- get reviewed, write tests, eliminate warnings, run tests, avoid mass-changes. -->
しかし、開発者は少なくとも次に示すことに気をとどめておくべきです:
査読を受けること、テストを書くこと、警告をなくすこと、テストを走らせること、大規模な変更を避けること。
</SUMMARY>
<BODY>
<p>
</p>
<ul>
<li>
<!-- All code changes must be reviewed. -->
全てのコードの変更は査読されなければなりません。
<!-- You should expect that your code will be reviewed by other hackers, -->
<!-- and that you will be assigned other hackers' code to review. -->
自分のコードが他のハッカーに査読されること、
また他のハッカーのコードの査読への参加を期待するべきです。
<!-- Part of the review criteria will be that code obeys -->
<!-- the coding standards in this document. -->
査読の際の基準の一つとして、この文書にあるコーディング基準をコードが守っているかを調べてください。
</li>
<li>
<!-- You must write and check-in tests for new code that you write and old bugs you fix. -->
新しいコードを書いたときと古いバグを修正したときは、
テストを書いてチェックインしなければなりません。
<!-- There must be a unit test for every API function, -->
<!-- and any previously failing case. -->
全てのAPI関数と以前存在したバグに対するユニットテストがなければなりません。
<!-- Your work is not truly done until this activity is complete. -->
あなたの仕事が完了するのはこの活動が終了した時です。
<!-- Estimating tasks must include the time it takes to produce such tests. -->
工数の見積もりはこのようなテストを書く時間を含んでいなければなりません。
</li>
<li>
<!-- Your code must compile -->
<!-- without any compilation error or warning messages whatsoever. -->
あなたのコードは、如何なるコンパイルエラーや警告メッセージを発生させずにコンパイル出来ないとなりません。
<!-- If the compiler issues warnings that should be ignored, -->
<!-- muffle those warnings using the -->
<!-- <code>UIOP:WITH-MUFFLED-COMPILER-CONDITIONS</code> and -->
<!-- <code>UIOP:*UNINTERESTING-COMPILER-CONDITIONS*</code> -->
<!-- framework (part of <code>UIOP</code>, part of <code>ASDF 3</code>), -->
<!-- either around the entire project, or around individual files -->
<!-- (using <code>ASDF</code>'s <code>:around-compile</code> hooks). -->
もし、コンパイラが無視すべき警告を発したら
(<code>ASDF 3</code>に含まれる<code>UIOP</code>の)
<code>UIOP:WITH-MUFFLED-COMPILER-CONDITIONS</code>と
<code>UIOP:*UNINTERESTING-COMPILER-CONDITIONS*</code>フレームワーク
をプロジェクト全体か独立したファイルに対して使い、
その警告を消し去ってください
(<code>ASDF</code>の<code>:around-compile</code>フックを使います)。
</li>
<li>
<!-- All code should be checked in an appropriate source control system, -->
<!-- in a way that allows for complete reproducibility of -->
<!-- build, test and execution of -->
<!-- the code that is, has been or may be deployed. -->
デプロイしている、したことがある、出来る状態にある全てのコードの、ビルド、テスト、実行が完全に再現可能になるように、
適切なソースコード管理システムにチェックインすべきです。
</li>
<li>
<!-- You must run the "precheckin" tests, and each component must pass -->
<!-- its unit tests successfully before you commit any code. -->
どんなコードもチェックインするときは、その前に
「チェックイン前」テストを走らせ、それぞれのコンポーネントはそのユニットテストを通過しなければなりません。
</li>
<li>
<!-- You should incorporate code coverage into your testing process. -->
<!-- Tests are not sufficient -->
<!-- if they do not cover all new and updated code; -->
テスト工程にコードカバレッジを組み込むべきです。
テストが新しいコードと更新されたコードの全てを対象にできていないのなら、
そのテストは十分ではありません。
<!-- code that for whatever reason cannot be included in coverage results -->
<!-- should be clearly marked as such including the reason. -->
どんな理由であれ、カバレッジに含む事の出来ないコードには、理由を含めそうであると明確に目印を付しておくべきです。
</li>
<li>
<!-- Many people develop on branches. -->
多くの人々はブランチ上で開発します。
<!-- You must get permission to undertake mass-changes -->
<!-- (e.g. mass reindentations) -->
<!-- so that we can coordinate in advance, -->
<!-- and give branch residents time to get back on the mainline -->
巨大な変更（例えば全体にわたる字下げのやり直し）に着手する際は
他の開発者が前もって連携できるように、許可を得て、
ブランチがメインラインと統合する時間を与えなければなりません。
</li>
</ul>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="Formatting">
<!-- <STYLEPOINT title="Spelling and Abbreviations"> -->
<STYLEPOINT title="綴りと略語">
<SUMMARY>
<p>
<!-- You must use correct spelling in your comments, -->
<!-- and most importantly in your identifiers. -->
コメントでは正しい綴りを用いなければなりません。とりわけ識別子では正しい綴りが重要になります。
</p>
<p>
<!-- When several correct spellings exist (including American vs English), -->
<!-- and there isn't a consensus amongst developers as which to use, -->
<!-- you should choose the shorter spelling. -->
複数の正しい綴りが存在する場合(米国式綴り vs 英国式綴り)で、
開発者間でどちらの綴りを採用するかのコンセンサスが存在していない場合、短い方の綴りを採用するべきです。
</p>
<p>
<!-- You must use only common and domain-specific abbreviations, and -->
<!-- must be consistent with these abbreviations. You may abbreviate -->
<!-- lexical variables of limited scope in order to avoid overly-long -->
<!-- symbol names. -->
略語は、良く使われドメインに特化したものだけを利用するようにしなければなりません。
また、それらの略語には一貫性を持たせなくてはなりません。
スコープが限定されたレキシカル変数の名前では、長すぎる名前を避けるために名前を略しても良いでしょう。
</p>
</SUMMARY>
<BODY>
<p>
<!-- If you're not sure, consult a dictionary, -->
<!-- Google for alternative spellings, -->
<!-- or ask a local expert. -->
不確かな場合、辞書で調べたり、他の綴りがないかGoogleで検索したり、近くの詳しい人に訊きましょう。
</p>
<p>
<!-- Here are examples of choosing the correct spelling: -->
下記に正しい綴りの選択例を挙げます:
</p>
<ul>
<li>
<!-- Use "complimentary" in the sense of a meal or beverage -->
<!-- that is not paid for by the recipient, not "complementary". -->
"complimentary"は、受給者が無料でドリンクや、食べ物を得るようなことに使う。
"complementary"(補足的な)ではない。
</li>
<li>
<!-- Use "existent" and "nonexistent", not "existant". -->
<!-- Use "existence", not "existance". -->
"existent"(実在する)か"nonexistent"(存在しない)を使い、"existant"という綴りは使わない。
"existence"と綴り、"existance"とは綴らない。
</li>
<li>
<!-- Use "hierarchy" not "heirarchy". -->
"hierarchy"と綴り、"heirarchy"とは綴らない。
</li>
<li>
<!-- Use "precede" not "preceed". -->
"precede"と綴り、"preceed"とは綴らない。
</li>
<li>
<!-- Use "weird", not "wierd". -->
"weird"と綴り、"wierd"とは綴らない。
</li>
</ul>
<p>
<!-- Here are examples of choosing the shorter spelling: -->
下記は、短い綴りの採択例です:
</p>
<ul>
<li>
<!-- Use "canceled", not "cancelled" -->
"canceled"と綴り、"cancelled"とは綴らない。
</li>
<li>
<!-- Use "queuing", not "queueing". -->
"queuing"と綴り、"queueing"とは綴らない。
</li>
<li>
<!-- Use "signaled", not "signalled"; -->
"signaled"と綴り、"signalled"とは綴らない。
</li>
<li>
<!-- Use "traveled", not "travelled". -->
"traveled"と綴り、"travelled"とは綴らない。
</li>
<li>
<!-- Use "aluminum", not "aluminium" -->
"aluminum"と綴り、"aluminium"とは綴らない。
</li>
<li>
<!-- Use "oriented", not "orientated" -->
"oriented"と綴り、"orientated"とは綴らない。
</li>
<li>
<!-- Use "color", not "colour" -->
"color"と綴り、"colour"とは綴らない。
</li>
<li>
<!-- Use "behavior", not "behaviour" -->
"behavior"と綴り、"behaviour"とは綴らない。
</li>
</ul>
<p>
<!-- Make appropriate exceptions for industry standard nomenclature/jargon, -->
<!-- including plain misspellings. -->
<!-- For instance: -->
業界標準な術語/ジャーゴン(単なる綴り間違いも含む)は適切に例外として扱います。
例えば:
</p>
<ul>
<li>
<!-- Use "referer", not "referrer", in the context of the HTTP protocol. -->
HTTPプロトコルの文脈では、"referer"と綴り、"referrer"とは綴らない。
</li>
</ul>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="行の長さ"><!-- Line length -->
<SUMMARY>
<!-- You should format source code so that no line is longer than 100 characters. -->
ソースコード中に100文字を超える行がないように整形すべきです。
</SUMMARY>
<BODY>
<p>
<!-- Some line length restriction is better than none at all. -->
行の長さの制限は何の制限がないよりましです。
<!-- While old text terminals used to make 80 columns the standard, -->
<!-- these days, allowing 100 columns seems better, -->
<!-- since good style encourages the use of -->
<!-- descriptive variables and function names. -->
古いテキスト端末ではかつて80文字を基準としていましたが、
今日では変数や関数に説明的な名前を付けることが良いスタイルとして推奨されているので、
100文字まで許すのが良さそうです。
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="字下げ"><!-- Indentation -->
<SUMMARY>
<p>
<!-- Indent your code the way a properly configured GNU Emacs does. -->
コードの字下げは適切に設定されたGNU Emacsのやり方に従います。
</p>
<p>
<!-- Maintain a consistent indentation style throughout a project. -->
プロジェクトを通して字下げのスタイルが一貫するように管理しましょう。
</p>
<p>
<!-- Indent carefully to make the code easier to understand. -->
字下げを丁寧に行い、コードの理解を簡単にしましょう。
</p>
</SUMMARY>
<BODY>
<p>
<!--
Common Lisp indentation in Emacs is provided by the cl-indent library.
The latest version of cl-indent is packaged with
<a HREF="https://www.common-lisp.net/project/slime/">SLIME</a>
(under contrib/slime-cl-indent.el). After installing SLIME, set up Emacs
to load SLIME automatically using
<a HREF="https://www.common-lisp.net/project/slime/doc/html/Loading-Contribs.html">these instructions</a>, adding slime-indentation to the list of
contrib libraries to be loaded in the call to slime-setup.
-->
EmacsでのCommon Lispの字下げは、cl-indentライブラリが提供されています。
最新のcl-indentバージョンは、<a HREF="https://www.common-lisp.net/project/slime/">SLIME</a>に同梱されています(contrib/slime-cl-indent.el)。
SLIMEを導入した後、EmacsがSLIMEを自動でロードするよう、<a HREF="https://www.common-lisp.net/project/slime/doc/html/Loading-Contribs.html">この手順</a>で設定します。