コーディング標準文書の作成

私は、主な仕事がSCADAとPLCであり、他の制御システムのスタッフと一緒に、制御システムの会社で働いています。

ソフトウェア開発は、社内のプロジェクト管理および評価システムを作成する決定が下されるまで、あちこちで少しだけ離れて、会社が実際に行うものではありません。

このプロジェクトは、もともとソフトウェアの人としてここに来た人々によって引き継がれ、私たちはほとんどジュニアです。

プロジェクトは小さなものから始まったので、デザイン、データベースなどのようなものだけをドキュメント化しましたが、コーディング形式/規約については実際には合意しませんでした。

StyleCopを使用してコードを適切に文書化したことを確認しましたが、適切な標準を継続し、今後大きな開発作業が行われる場合は誰でも作業できるように、コーディング規約/プラクティスの公式文書が必要だと感じています良いベースプレートがあります。

そこに問題があります、コーディング規約と標準のための文書をどのように作成するのか分かりません、私が考えることができるのは良いプラクティスと悪いプラクティスの例です（たとえば、変数に名前を付けるときのキャメルケース、ハンガリー語の表記を避けるなど）有能なプログラマー（明らかに）ですが、この種のチャーターはありません。

それにポイントを置くために、私の質問は次のとおりです。良いコーディング標準文書の重要な側面と内容は何ですか？

優れたコーディング標準文書の重要な側面と内容は何ですか？

1. されているコードの自動化されたチェックを可能にするツールでサポートされています。一部のルールに一致しないコードのバージョン管理にコミットできないことがわかっている場合は、コード内のこれらのルールに従うことをお勧めします。一方、仲間のプログラマーがどこかで規則に従う必要があると書いたとしても、それらの規則についてくだらないことはしません。

2. されて考え抜かれた、代わりにあなたの個人的な見解であることの。「これからは、リージョンが好きではないので、これ以上リージョンを使用しません。」とはっきりとは言わないでしょう。むしろ、地域はコードの成長を促進し、大きな問題を解決しないと説明します。

   理由は、最初のケースでは、同僚が「まあ、私は地域が好きなので、私はまだそれらを使用するだろう」と答えるからです。一方、2番目のケースでは、建設的な批判、提案、議論を受け入れることに同意しない人々を強制し、最終的には元の意見を変えさせます。

3. されて十分に文書化。文書の欠如は混乱と解釈の余地を生み出します。混乱と解釈の可能性はスタイルの違いにつながります。つまり、標準が抑制したいものです。

4. 社外にいることを含め、広範囲に及ぶこと。20人のプログラマが使用する「標準」は、世界中の何十万人もの開発者が知っている標準よりも標準が劣っています。

StyleCopについて話しているので、アプリケーションは.NET Framework言語の1つで書かれていると思います。

その場合は、別のやり方をする重大な理由がない限り、Microsoftのガイドラインに従ってください。独自の標準を作成するよりも、いくつかの利点があります。前の4つのポイントを取得します。

1. 独自の標準に合わせてStyleCopルールを書き換える必要はありません。独自のルールを記述するのは難しいとは言いませんが、それを避けることができれば、代わりに何か役に立つことをする時間があることを意味します。

2. Microsoftのガイドラインは非常によく考えられています。それらのいくつかに同意しない場合、それらを理解していないためである可能性があります。これはまさに私の場合でした。C＃開発を始めたとき、いくつかのルールがまったく馬鹿げていることがわかりました。今、私はそれらに完全に同意します。なぜなら、彼らがこのように書かれた理由をようやく理解したからです。

3. Microsoftのガイドラインは十分に文書化されているため、独自のドキュメントを作成する必要はありません。

4. 後であなたの会社に採用される新しい開発者は、すでにMicrosofのコーディング標準に精通しているかもしれません。誰もあなたの内部コーディングスタイルに慣れていない可能性があります。

最初に注意すべき重要なことは、コーディング標準文書は正誤ではないということです。それは善悪についてではなく、どちらの方法が優れているかということでもありません。

コーディング標準文書の目的は、開発者が他の人のスタイルを読むために必要なメンタリティを変更することなく、ある人から別の人に簡単に切り替えられるように、すべてのコードが同じように設計、作成、レイアウトされるようにすることです。

それはすべて均一性についてであり、「善悪」については何もありません

それを念頭に置いて、コーディング標準文書で明確にする必要があるいくつかのことを以下に示します。

命名規則

メソッド、変数、クラス、インターフェースにどのように名前を付けますか？どの表記を使用しますか？

また、私たちの標準に含まれる他の何かは、SQLの標準を分割したものでした。そのため、テーブル、プロシージャ、列、IDフィールド、トリガーなどの名前は似ていました。

くぼみ

インデントに何を使用しますか？単一のタブですか？3つのスペース？

レイアウト

ブレースは、オープニング方法の行と同じ行に保持されますか？（一般的にjava）または次の行またはそれ自体の行ですか？（通常はC＃）

例外処理/ロギング

例外処理とロギングの標準は何ですか？それはすべて自家栽培ですか、それともサードパーティのツールを使用していますか？どのように使用する必要がありますか？

コメントする

文法の正確さを指示する基準があり、コメントは同じ行ではなく前または後の行で始まるため、読みやすくなります。コメントはコードと同じ深さにインデントする必要がありますか？大きなテキストの周囲に使用されるコメントの境界線を受け入れますか？

説明のメソッドの\\\はどうですか？これらは使用されますか？いつ？

暴露

すべてのメソッドとフィールドに、可能な限り低いレベルのアクセスを実装する必要がありますか？

また、注意すべき重要なことです。優れた標準ドキュメントは、コードのレビューに役立ちますが、これらの最小標準を満たしますか？

これらのドキュメントの1つに入れることができるものの表面をかろうじて傷つけましたが、KISS

長く、退屈で、通り抜けることができないようにしないでください。そうしないと、それらの基準がそのまま守られないので、単純にしてください。

私はこのプロセスを何度も繰り返していました。最も成功した（とにかくでこぼこ）アプローチは、有名な会社から「コーディング標準」ドキュメントを取得し、ニーズに合わせて修正することでした。

たとえば、私はこれを見つけました：http : //www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

とにかく、火炎放射器を手元に置いておきます。

乾杯、

標準文書はたいてい小さなものに汗をかき、大きな全体像を無視しようとするため、ほとんどの標準文書は嫌いです。

たとえば、それらのほとんどすべてが、変数に名前を付ける方法や角かっこを配置する方法を説明します。これは純粋なスタイルであり、開発者コードのグループを正しく実際に支援することはほとんどありません。ディレクトリ構造やコードレイアウトなどを無視します。演算子の間にいくつのスペースを入れ、メソッドの間に何行の空白行を入れるかを正確に伝える標準文書を見てきました。これらのすべては、通常、彼らが本当にどれほど無意味であるかを示すルールの例外のトンで終わります、そして、彼らはとても大きく、誰も彼らに従うことができません。 。

今、私にとっては、多くの異なる人々からのソフトウェアの多くの異なるビットを使用しており、それらはすべて異なるスタイルを持っています。私はこれに単純に慣れますが、すべての開発グループに共通のスタイルがないと文句を言いません。コードがプロジェクト全体で共通のスタイルである限り、そのスタイルが何であるかは本当に気にしません。それで、すべての標準文書に関する私の最初のルールは、プロジェクト内で一貫したコーディングスタイルを維持することです。ブラケットがすべて同じである限り、誰もブラケットの位置にイチジクを与えるべきではありません。宗教戦争に参加し、それらを突き出す:)

2つ目はコードレイアウトです。コードを拾うとき、他の似たような作品と同じような線に沿ってレイアウトされていることを確認したいと思います。Webサービスがある場合、wsdlコントラクトの名前を明確にしたいのですが、実装の名前を明確にしたいです。誰かがファイルやクラスのまったく新しいレイアウトを思い付かないようにしたいと思います。それは私が迷惑な「コードをハント」する必要があることを意味します。私が取り組んだ最後のプロジェクトと同じように見える場合、探しているものをどこで見つけることができるかすぐにわかります。おそらく、私が知っている他の人のコードを操作するための最大の助けになります。そのため、コードのレイアウトの構造を保持します（ドキュメントのドキュメントフォルダー、インターフェイスのインターフェイスなど-動作するものは何でも、それを守ります）。

コードアーティファクトも存在する必要があるため、予期されるエラー処理が例外かエラーコードかを示す必要があります。使用中のアーキテクチャ機能を文書化します。また、使用するログの種類と、ユーザーにログ/エラー処理を提示する方法、または野生のコードを管理するために使用されるサブシステムを示す必要があります。私はすべてのプロジェクトが異なるログを記録する場所で働いていました-各コードリリースが独自の異なる運用文書を持っていなければならなかったのは哀れなことでした。イベントログ、ログファイル（その場合）などはすべてここで有効です。同じことは、コードの他の一般的な側面にも適用されます-構成方法（一部のプログラムでは.configファイル、カスタムDB、コマンドラインパラメーター、または他のレジストリでは使用しません）。

要するに、重要なのは一貫性だけです。そして、巨大な標準文書は読みすぎて覚えるには多すぎるので、私は人々に見えないもの（例えば、ロギングのような建築標準）を人々に知らせ、彼らが書いているコードを現在の内容と一貫性を保つように伝えることを好む。また、コードがまだない場合は、標準ドキュメントは必要ありません！（まあ、あなたがそれを有用にするのに十分なことを書くまでではありません）。

だから、その要点から：法的文書を作ろうとせず、コーディングだけでなく、コードがどのように機能し、コードが他の人々の期待にどのように適合するかを考えてください。その後、人々が良いコードを実行することを信頼すると、彼らが実行することがわかります。（そして彼らがそうしなければ、あなたは彼らと一緒に言葉を持つことができます、法律のようにそれを置く必要はありません）。

しないでください、それは時間とエネルギーの完全な無駄です。StyleCopは優れており、あなたやチームの誰よりもはるかに経験豊富で賢い人々によって長年にわたって設立されました。抱きしめて愛してください！それは継続的にあなたをガイドします、それはそれを読むのが面倒な人を待っているどんな文書よりも優れています。