標準文書

Question

私は、約15人の開発者からなるチームのためのコーディング標準文書を作成しています。プロジェクトの負荷は年間10〜15プロジェクトです。他のセクション（ここでは私がここに投稿するかもしれません）の中で、私はコードの書式設定に関するセクションを書いています。したがって、何らかの理由で何らかの基本的で一貫したコードの書式設定/命名標準を確立することが賢明だと思います。

私はこのチームから過去3年間に書かれた約10のプロジェクトを見てきましたが、私は明らかに非常に幅広いスタイルを見つけています。請負業者は出入りし、時には出入りし、場合によってはチームサイズを2倍にすることもあります。

私はコードフォーマットとネーミング標準のためのいくつかの提案を探していますが、それは本当に報われましたが、それは本当に正当化することもできます。一貫性と共有パターンはコードをより保守性のあるものにするためには長い道のりだと思いますが、上記の標準を定義する際に考慮する必要がある他のものはありますか？

• どのようにラインアップかっこですか？クラス、メソッド、tryブロック文、switch文、elseブロックなどを扱うときは、同じ括弧のガイドラインに従っていますか？

• 列のフィールドを並べていますか？プライベート変数にアンダースコアを付ける/接頭辞しますか？ファイル内の詳細を見つけるのを容易にするために、命名規則に従っていますか？あなたのクラスのメンバーをどのように注文しますか？

名前空間、パッケージングまたはソースコードフォルダ/組織の標準についてはどうでしょうか？私はこれらの基準を規定オフベンチャーの前に - 私はに慣れているもの以外、より受け入れられ、慣行があるかどうかを確認するために興味

<com|org|...>.<company>.<app>.<layer>.<function>.ClassName 

：私のような何かを開始する傾向があります。すでにオンラインで公開されている標準へのリンクも素晴らしいかもしれません。

Answer 1

まず、自分の言語で動作する自動コードフォーマッタを見つけます。理由：文書が何を言っても、人々は必然的に規則を破るでしょう。コードレビューでは、フォーマットを介してコードを実行する方がはるかに簡単です。

言語を既存の標準（Java、C＃など）で使用している場合は、使用するのが最も簡単です。または、少なくとも最初の草案として開始してください。サンは彼らの書式設定のルールに多くの考えを置いた。あなたはそれを活用するかもしれません。

いずれの場合でも、括弧の位置や空白の使用のようなさまざまなものは、バグの生産性や理解容易性、または蔓延に測定可能な影響を及ぼさないことを多くの研究が示していることを忘れないでください。ちょうどのいずれかのが鍵です。

Answer 2

明らかに言語や技術によって異なります。あなたの例の名前空間の見た目で私はJavaを推測しようとしています。この場合、http://java.sun.com/docs/codeconv/は本当に良い場所です。また、すべてのプロジェクトを似たように見せるmavenの標準ディレクトリ構造のようなものを見たいかもしれません。

Answer 3

私は2番目のジェイソンの提案に行くつもりです。

ほとんどの場合、perlで動作する10-12のチームの標準文書を完成させました。この文書では、複雑なデータ構造に対して「ペルチッティのような字下げ」を使用すると述べています。また、この標準を満たすためにコードを整理するための例を提供しました。それは非常に明確で、言語のための非常に多くの業界標準でしたので、私たちはチームによってそれについて素晴らしいブフォッフを持っていました。

このドキュメントを書くときには、私たちのリポジトリに素晴らしいコードのいくつかの例を尋ねました。私はテンプレートを作成するよりもスマートな設計者である他の標準ドキュメントを探して少し調べました。それは、マイクロマネージャ領域に入ることなく簡潔かつ実用的であることは困難でしたが、それに相当な価値がありました。 のいずれか標準が確かに重要です。

うまくいきますように！自動車業界から来る

Answer 4

は、ここでは具体的な理由のために使用され、いくつかのスタイルの規格です：

は常に制御構造でのかっこを使用し、別の行に配置します。これにより、コードを追加したり、コードを追加したり、誤ってコントロール構造内にコードを含めたりしないという問題が排除されます。

if(...) 
{ 

} 

すべてのスイッチ/セレクトには、デフォルトのケースがあります。デフォルトのケースは、有効なパスでない場合はエラーを記録します。

上記と同じ理由で、if ... elseif ...制御構造は、有効なパスでない場合にもエラーをログに記録するデフォルトのelseで終了する必要があります。 1つのif文でこれを必要としません。

ループまたは制御構造が意図的に空の場合は、意図的であることを示すためにセミコロンが常に配置されます。

while(stillwaiting()) 
{ 
    ; 
} 

命名標準には、typedef、定義済みの定数、モジュールのグローバル変数などのスタイルが大きく異なります。変数名には型が含まれます。あなたは名前を見ることができ、それが関係するモジュール、スコープ、タイプを知ることができます。これにより、タイプなどのエラーを簡単に検出することができます。

他にもいくつかありますが、これは私の頭の中のトップです。

-adam