Geekly Articles each Day

コードスタイルのガイドライン

Java言語の規則


標準のJavaコード規則に従います。 それらにいくつかのルールを追加しました：
  1. 例外：説明なしにそれらを傍受または無視しないでください。
  2. 例外：スタックのルートで、ライブラリ内のコードを除き、一般化された例外を使用しないでください。
  3. ファイナライザー：それらを使用しないでください。
  4. インポート：インポートを完全に指定します。


Javaライブラリルール


Android用のJavaライブラリとツールの使用に関しては合意があります。 場合によっては、たとえば、承認されていないパターンまたはライブラリを使用する可能性のある古いコードを使用するなど、規則を変更できます。

Javaスタイルのルール


すべてのファイルのスタイルが一貫していると、プログラムのメンテナンスがはるかに簡単になります。 Sunは、Javaプログラミング言語のコード規約で定義されている標準のJavaプログラミングスタイルに従いますが、いくつかの例外と追加があります。 このスタイルガイドは包括的かつ包括的であり、Javaコミュニティでも広く使用されています。

さらに、コードには次のルールを使用する必要があります。
  1. コメント/ Javadoc：それらを書いてください。 標準スタイルを使用します。
  2. 短いメソッド：巨大なメソッドを作成しないでください。
  3. フィールド：ファイルの先頭、またはそれらを使用するメソッドの直前になければなりません。
  4. ローカル変数：スコープを制限します。
  5. インポート：android; サードパーティ（アルファベット順）; Java（x）
  6. インデント：タブなしの4つのスペース。
  7. 行の長さ：100文字。
  8. フィールド名：非パブリックおよび非静的フィールドは「m」で始まります。
  9. 中括弧：開き中括弧は別の行にありません。
  10. 注釈：標準の注釈を使用します。
  11. 略語：略語を名前の単語として使用します。たとえば、XmlHttpRequest、getUrl（）など。
  12. TODOスタイル：「TODO：ここに説明を書いてください。」
  13. 一貫性：あなたの周りを見てください。

Java言語の規則


例外を無視しないでください

たとえば、例外を無視するコードを記述できます。
void setServerPort(String value) { try { serverPort = Integer.parseInt(value); } catch (NumberFormatException e) { } }

絶対にしないでください。 コードがこのような状態に遭遇することは決してないと思うか、この状態を処理することは重要ではないと思いますが、例外を無視すると隠れた問題が生じます。 基本的にすべての例外を処理する必要があります。 それぞれの場合の詳細は、状況によって異なります。
許容可能な代替：

一般的な例外をキャッチしません

例外処理が面倒で、次のような記述をしたい場合があります。
 try { someComplicatedIOFunction(); // may throw IOException someComplicatedParsingFunction(); // may throw ParsingException someComplicatedSecurityFunction(); // may throw SecurityException // phew, made it all the way } catch (Exception e) { // I'll just catch all exceptions handleError(); // with one generic handler! }

あなたはそれをするべきではありません。 一番下の行は、予期しない例外が存在する可能性があり、その結果、アプリケーションレベルでエラーがキャッチされることです。 つまり、誰かが新しいタイプの例外を追加した場合、コンパイラはこれが別のエラーであることを理解するのを助けることができません。

この規則にはまれな例外があります：特定のテストコード、またはすべての種類のエラーをインターセプトするトップレベルコード（エラーがユーザーインターフェイスに表示されないようにするため、または何らかの種類のバッチタスクを続行するため）。

一般的な例外の代替：

覚えておいてください：例外はあなたの友達です！ コンパイラーがそれらをキャッチしていないことを示すとき、怒ってはいけません。

ファイナライザー

概要：ファイナライザは、オブジェクトがガベージコレクタによって収集される前にプログラムコードを実行する方法です。
長所 ：特に外部リソースのクリーニングに役立つ場合があります。
短所 ：ファイナライザがいつ呼び出されるか、一般的にはファイナライザが呼び出されるかどうかは保証されません。

解決策 ：ファイナライザーを使用しません。 ほとんどの場合、ファイナライザに必要なものはすべて、例外処理でできます。 ファイナライザーが本当に必要な場合は、close（）メソッドを宣言し、正確に呼び出されるタイミングを文書化します。

輸入品

インポートのワイルドカード

概要 ：fooパッケージのBarクラスを使用する場合、これを行うには2つの方法があります。
  1.  import foo.*; 
  2.  import foo.Bar;

プロ＃1 ：可能性のあるimportステートメントの数を潜在的に減らします。
プロ＃2 ：実際に使用されているクラスを明確にします。 コードをサポートする人にとってコードを読みやすくします。

解決策 ：スタイル＃2を使用して、Androidコードをインポートします。 明示的な例外は、標準ライブラリ（java.util。*、Java.io。*など）および単体テストコード（junit.framework。*）に対して作成されます。

コメント/ Javadoc


各ファイルには、最初に著作権表示が必要です。 次に、パッケージとインポート文の宣言があり、各ブロックは空の文字列で区切られています。 その後にクラスまたはインターフェイスの宣言が続きます。 クラスの動作をJavadocコメントで説明します。
 /* * Copyright (C) 2010 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.android.internal.foo; import android.os.Blah; import android.view.Yada; import java.sql.ResultSet; import java.sql.SQLException; /** * Does X and Y and provides an abstraction for Z. */ public class Foo { ... }

各クラスおよび重要なパブリックメソッドには、その動作を説明する少なくとも1つのフレーズを含むJavadocが含まれている必要があります。 フレーズは3人称の説明動詞で始まる必要があります。 例：
 /** Returns the correctly rounded positive square root of a double value. */ static double sqrt(double a) { } /** * Constructs a new String by converting the specified array of * bytes using the platform's default character encoding. */ public String(byte[] bytes) { }

Javadocで「sets Foo」のみと表示されている場合、setFoo（）のような単純なgetおよびsetメソッドのJavadocを記述する必要はありません。 メソッドがより複雑なことを行う場合（たとえば、特定の制限を遵守する場合、またはそのアクションがそれ自体の外側で重要な効果を発揮する場合）、文書化する必要があります。 そして、これがFooの意味の単なる説明ではない場合は、それも文書化する必要があります。

一般に、Javadocがパブリックであるかどうかに関係なく、作成したメソッドはすべてJavadocから恩恵を受けます。 パブリックメソッドはAPIの一部であるため、Javadocでの説明が必要です。

Javadocを作成するには、 Sun Javadocの規則に従う必要があります。

短い方法


メソッドは小さく、特定の問題を可能な限り解決する必要があります。 ただし、大きなメソッドが有用な場合があるため、メソッドの長さに厳密な制限はありません。 メソッドが40行を超える場合は、プログラムの構造に違反することなく分割できるかどうかを検討する必要があります。

ローカル変数


ローカル変数のスコープは最小化する必要があります。 これにより、コードの可読性と保守性が向上し、エラーの可能性が減少します。 各変数は、変数を使用するすべての可能な場所を囲む最も深いブロックで宣言する必要があります。

ローカル変数は、最初に使用する必要がある場所で宣言する必要があります。 ほとんどすべてのローカル変数には初期化子が必要です。 それでも変数を正確に初期化する方法がわからない場合は、それがわかるまでその宣言を延期する必要があります。

try-catchブロックには1つの例外があります。 チェック例外をスローするメソッドのreturnステートメントを使用して変数を初期化する場合、tryブロックで初期化する必要があります。 変数をtryブロックの外側で使用する必要がある場合は、変数をその前で宣言します。変数を正確に初期化する方法を知っていてもかまいません。
 // Instantiate class cl, which represents some sort of Set Set s = null; try { s = (Set) cl.newInstance(); } catch(IllegalAccessException e) { throw new IllegalArgumentException(cl + " not accessible"); } catch(InstantiationException e) { throw new IllegalArgumentException(cl + " not instantiable"); } // Exercise the set s.addAll(Arrays.asList(args));

ただし、この場合でも、メソッドにtry-catchブロックをカプセル化することで回避できます。
 Set createSet(Class cl) { // Instantiate class cl, which represents some sort of Set try { return (Set) cl.newInstance(); } catch(IllegalAccessException e) { throw new IllegalArgumentException(cl + " not accessible"); } catch(InstantiationException e) { throw new IllegalArgumentException(cl + " not instantiable"); } } ... // Exercise the set Set s = createSet(cl); s.addAll(Arrays.asList(args));

ループ内の変数は、乗り越えられない理由がない限り、ステートメント自体の中で宣言する必要があります。
 for (int i = 0; i <= n; i++) { doSomething(i); } for (Iterator i = c.iterator(); i.hasNext(); ) { doSomethingElse(i.next()); }


輸入品


インポート文の順序は次のとおりです。
  1. Androidのインポート。
  2. サードパーティのインポート（com、junit、net、org）。
  3. javaおよびjavax。

IDE設定に完全に準拠するには、インポートは次のようになります。

なんで？
順序は次のとおりです。

くぼみ


ブロックには4つのスペースを使用します。 タブは使用しません。 関数呼び出しや割り当てを含む改行には、たとえば次のように8つのスペースを使用します。
 Instrument i = someLongExpression(that, wouldNotFit, on, one, line);

そしてとても間違っています：
 Instrument i = someLongExpression(that, wouldNotFit, on, one, line);

フィールド名



例：
 public class MyClass { public static final int SOME_CONSTANT = 42; public int publicField; private static MyClass sSingleton; int mPackagePrivate; private int mPrivate; protected int mProtected; }

中括弧


中括弧を開く場合、別の行は強調表示されず、前のコードと同じ行にあります。
 class MyClass { int func() { if (something) { // ... } else if (somethingElse) { // ... } else { // ... } } }

条件ステートメントには中括弧が必要です。 例外は、条件ステートメントとその本体が同じ行に配置されている場合です。 つまり、次のように書くことができます。
 if (condition) { body(); // ok } if (condition) body(); // ok

しかし、それは不可能です。
 if (condition) body(); // bad

行の長さ


コード内の各テキスト行は、100文字以内にする必要があります。
例外：コメントにサンプルコマンドまたはURLが含まれる場合（コピー/貼り付けを使用する方が便利です）。
例外：インポート文字列は100文字を超える場合があります。これは人々がめったに見ないためです。 また、ツールの作成が簡単になります。

名前の略語


頭字語と略語を単語と考えてください。 名前はより読みやすくなります：
よし悪い
XmlHttpRequestXMLHTTPRequest
getCustomerIdgetCustomerID

このスタイルは、略語と略語がフルネームの場合にも適用されます。
よし悪い
クラスhtmlクラスHTML
文字列のURL。文字列URL
ロングID;長いID;


TODOスタイル


一時的、短期的、または良いが理想的ではないコードにはTODOコメントを使用します。 コメントには「TODO：」を含める必要があります。例：
 // TODO: Remove this code after the UrlTable2 has been checked in. // TODO: Change this to use a flag instead of a constant.

コメントが「将来何かをする」の場合は、特定の日付（2011年1月1日）、または特定の「バージョン2.1以降の削除」イベントが含まれていることを確認してください。

コヒーレンス


コードを変更する場合は、周囲のコードを見てそのスタイルを判断するために少し時間がかかります。 スペースが使用されている場合は、それらを使用する必要があります。 コメントに小さな星のセットが含まれている場合は、それらを使用する必要があります。

コードスタイルガイドラインのポイントは、共通の語彙を作成して、人々が言うことではなく、話すことに集中できるようにすることです。 人々がこの語彙を理解できるように、グローバルスタイルルールを導入します。 しかし、地元のスタイルも重要です。 ファイルに追加するコードが元のコードと大きく異なる場合、これにより将来の読者はリズムから外れ、構造を理解できなくなります。 これを避けるようにしてください。

Source: https://habr.com/ru/post/J112042/

More articles:


All Articles