This document describes a list of coding conventions that are required for code submissions to the project. By default, the coding conventions for most Open Source Projects should follow the existing coding conventions in the code that you are working on. For example, if the bracket is on the same line as the if statement, then you should write all your code to have that convention.
本ドキュメントでは、コード提出に必要なコーディング規約の一覧について述べます。 デフォルトでは、 ほとんどのオープンソースプロジェクトのコーディング規約は 自分が作業しているコードに既に存在するコーディング規約に従うべきです。 例えば、if 文と同じ行に括弧を置かなければならない場合は、 自分全てのコードがその規約に従うように記述しなければなりません。
Below is a list of coding conventions that are specific to Cactus, everything else not specificially mentioned here should follow the official Sun Java Coding Conventions.
Cactus 固有のコーディング規約の一覧を下に示します。 特にここで述べられていない全ての事柄は公式の Sun Java コーディング規約に従わなければなりません。
Having coding conventions is nice but having a way to ensure they are applied is even better ... :-)
コーディング規約があることは、とてもいいことですが、 それが適用されることを確認する方法があれば、もっといいです、、、:-)
The Cactus Ant build file has a checkstyle target which
performs coding conventions using the
Checkstyle tool. Drop the
Checkstyle jars in your ANT_HOME/lib, go in the
build/ directory and type ant checkstyle.
Cactus Ant ビルドファイルには、
Checkstyle ツールを用いて
コーディング規約を実践する
checkstyle ターゲットがあります。
Checkstyle jar を ANT_HOME/lib に置き、
build/ ディレクトリに移動し、
ant checkstyle と入力します。
Please run this target before committing any code.
どんなコードでもコミットする前に、 このターゲットを実行してください。
For class and method declaration, brackets should begin and end on a new line. Example :
クラスやメソッドの宣言では、 括弧は新しい行で始まり、終らなければなりません。 例えば次のようになります :
Brackets for blocks of code inside methods should begin and end
on the same line (this applies to if,
for, while, try/catch, ...).
Example :
メソッド中のコードブロックの括弧は、
同じ行で始まり、終らなければなりません。
(これは、if、for、while、
try/catch、などに対して適用されます)
例えば次のようになります :
Brackets are mandatory even for single line statements !
括弧をつけることは、一行の文に対しても義務付けられています。
keywords followed by a parenthesis should be separated by a space. Example :
括弧のついたキーワードはスペースで区切られなければなりません。 例 :
Blank space should appear after commas in argument lists. Binary operators should be separated from their operands by spaces :
引数リスト中のカンマの後には空白がなければなりません。 二項演算子はその演算記号をスペースで区切らなければなりません :
4 spaces. NO tabs. Period. We understand that a lot of you like to use tabs, but the fact of the matter is that in a distributed development environment, when the cvs commit messages get sent to a mailing list, they are almost impossible to read if you use tabs.
4 つの空白記号で、タブは無し。以上です。 皆さんの多くがタブを使いがちなのは知っていますが、 実際問題、分散開発環境においては、 cvs コミットメッセージがメーリングリストに送られるとき、 タブを使った場合、ほとんど読めないという事があるのです。
Javadoc SHOULD exist on all your class members (methods + class variables), including the private ones. Also, if you are working on existing code and there currently isn't a javadoc for that method/class/variable or whatever, then you should contribute and add it. This will improve the project as a whole.
自分の全てのクラスのメンバー(メソッド + クラス変数)には、 プライベートなものも含めて、 javadoc がなければなりません。 また、既存のコードで作業していて、 現状ではそのメソッド/クラス/変数に javadoc が無いなどの問題があったとき、 貢献して加えてください。 この事がプロジェクト全体を推進させるのです。
Also add code comments when you think it's necessary (like assumptions), especially when the code is not obvious.
また、(仮定のように)必要だと感じた場合、 特にコードが明瞭でない場合には、 コードにコメントを加えてください。
The Jakarta Apache/Cactus License MUST be placed at the top of each and every file.
Jakarta Apache/Cactus ライセンスは 個々の全てのファイルの先頭に置かなければなりません。
If you contribute to a file (code or documentation), add yourself to the top of the file (below the existing authors). For java files the preferred Javadoc format is:
ファイル(コードやドキュメント)に対して貢献した場合、 ファイルの先頭に(既存の作者の下に)自分の名前を加えることができます。 java ファイルの場合、 推奨される javadoc フォーマットは次の通りです:
Class variables should not have any prefix and must
be referenced using the this object. Example :
Class variables should not have any prefix
クラス変数は何も前にあってはならず、
this オブジェクトを使って
参照されなければなりません。例えば次のようになります :
Method parameters should be prefixed by "the" (for
differentiating them from inner variables). For example :
メソッド引数名は必ず "the" で始らなければなりません。
(内部変数と区別するためにです。)
例えば次のようになります :
Avoid lines longer than 80 characters for Code, comments, ...
コードやコメントで一行が 80 文字以上になるのを避けてください。
All .java files should have a @version tag like the one
below.
全ての .java ファイルには下に示すような @version タグが無ければなりません :
Do not use System.out to log. Instead,
use the Cactus logging classes which are a facade to Log4j. Use the
name of your class as the Log4j Category. For
example :
決してログ出力するのに System.out を
使わないでください。
代りに、Log4j をCategory として自分のクラス名を使ってください。 例は次の通りです :
Managing exceptions correctly requires experience. This is not supposed to be a guide on managing exceptions, simply a few best practices.
例外処理を正しく扱うには経験が必要です。 これは、例外処理を扱うガイドとして書かれたのではなく、 単に幾つかの最良の実例を示しただけです。
ChainedRuntimeException
for chaining runtime exceptions.
ChainedRuntimeException を提供しています。
Throwable or Exception and catch
specific exceptions instead.
Throwable あるいは Exception を
キャッチせず、代りに特定の例外をキャッチするように心がけてください。
An example :
例 :
All import statements should containing the full class
name of classes to import and should not use the "*"
notation :
全ての import 宣言には、
インポートするクラスのクラス名全体を入れるようにし、
"*" による表記を使わないようにしてください :
An example :
例 :