コーディング標準ドキュメントの作成
私は制御システム会社で働いています。主な仕事は [〜＃〜] scada [〜＃〜] および [〜＃〜] plc [〜＃〜] です。 、他の制御システムのものと一緒に。
社内のプロジェクト管理と評価システムを作成する決定が下されるまで、ソフトウェア開発は、ほんの少しの場合を除いて、会社が実際に行うことではありません。
このプロジェクトは、もともとソフトウェアの人々としてここにやってきた人々によって受け継がれており、私たちはほとんどが後輩です。
プロジェクトは小さなものから始まったので、設計、データベースなどのドキュメントのみをドキュメント化しましたが、コーディング形式/規約について実際に合意することはありませんでした。
私たちは StyleCop を使用してコードが十分に文書化されていることを確認するために使用し始めましたが、優れた標準を継続できるように、さらに主要な開発作業がある場合は、コーディング規約/プラクティスの公式文書が必要だと思います将来、それに取り組む人は誰でも良い基盤を持っています。
そこに問題があります。コーディング規約と標準のドキュメントを作成する方法がわかりません。考えられるのは、良い習慣と悪い習慣の例です（たとえば、変数に名前を付けるときのキャメルケース、ハンガリー語表記の回避など）。有能なプログラマーは（どうやら）いますが、この種のことについてのチャーターはありません。
それにポイントを置くために、私の質問は：優れたコーディング標準ドキュメントの主要な側面と内容は何ですか？
優れたコーディング標準ドキュメントの主要な側面と内容は何ですか？
コードの自動チェックを有効にするツールでサポートされている。一部のルールに一致しないコードのバージョン管理にコミットできないことがわかっている場合は、コードでそれらのルールに従うことをお勧めします。一方、他のプログラマーが私がルールに従う必要がある場所を書いた場合、それらのルールについてはくだらないことはしません。
であることよく考えて、あなたの個人的な意見ではなく。 「私はリージョンが好きではないため、今後はリージョンを使用しなくなります。」むしろ、 リージョンはコードの成長を促し、大きな問題を解決しないと説明します 。
その理由は、最初のケースでは、同僚が「まあ、私は地域が好きなので、引き続き使用する」と答えるからです。一方、2番目のケースでは、反対する人に建設的な批判、提案、および議論を強いることになり、最終的には元の意見を変えることになります。
十分に文書化されている。ドキュメントが不足すると混乱と解釈の余地;解釈の混乱と可能性は、スタイルの違い、つまり標準が抑制したいものにつながります。
であること社外を含む広範囲に。 20人のプログラマが使用する「標準」は、世界中の何十万人もの開発者が知っている標準よりも標準が劣っています。
StyleCopの話をしているので、アプリケーションは.NET Framework言語の1つで記述されていると思います。
その場合は、別の方法で行う深刻な理由がない限り、Microsoftのガイドラインに従ってください。独自の標準を作成するよりも、いくつかの利点があります。前の4つのポイントを取り上げます。
独自の標準に合わせるためにStyleCopルールを書き直す必要はありません。独自のルールを書くのは難しいとは言えませんが、それを避けることができれば、代わりに何か有用なことをする時間が増えることになります。
マイクロソフトのガイドラインは非常によく考えられています。それらのいくつかに同意しない場合、それらを理解していない可能性があります。これはまさに私の場合でした。 C＃の開発を始めたとき、いくつかのルールがまったくおかしかったことがわかりました。彼らがこのように書かれている理由をようやく理解したので、今、私はそれらに完全に同意します。
Microsoftのガイドラインは十分に文書化されているため、独自のドキュメントを作成する必要はありません。
後であなたの会社に雇われる新しい開発者は、すでにマイクロソフのコーディング標準に精通しているかもしれません。内部のコーディングスタイルを誰も知らない可能性があります。
注意すべき最初の重要なことは、コーディング標準のドキュメントは正誤についてではないということです。良い点と悪い点ではなく、どちらの方法が優れているかではありません。
コーディング標準ドキュメントの目的は、開発者が他の人のスタイルを読むために必要な考え方を変えることなく、ある人の作業から別の人の作業に簡単に切り替えられるように、すべてのコードが同じように設計、記述、レイアウトされていることを確認することです。
それはすべて均一性に関するものであり、「善悪」に関するものではありません
このことを念頭に置いて、コーディング標準ドキュメントで明確にすべきいくつかのことを次に示します。
命名規則
メソッド、変数、クラス、インターフェースにどのような名前を付けますか？どの表記を使用しますか？
また、私たちの標準に含まれている他の何かは、SQLの分割された標準であったため、テーブル、プロシージャ、列、IDフィールド、トリガーなどに同様の名前を付けました。
インデント
インデントには何を使用しますか？単一のタブ？ 3スペース？
レイアウト
ブレースは開始メソッド行と同じ行に保持されますか？ （一般的にJava）または次の行またはそれ自体の行？ （通常はC＃）
例外処理/ロギング
例外処理とロギングの基準は何ですか、すべて自社開発ですか、それともサードパーティのツールを使用していますか？それはどのように使用すべきですか？
コメント
文法の正確さを規定する基準があり、コメントが同じ行ではなく、前または後の行から始まると、読みやすくなります。コメントはコードと同じ深さまでインデントする必要がありますか？大きなテキストの周りに使用されるコメント枠を受け入れますか？
メソッドの\\\についてはどうですか？これらは使用されますか？いつ？
露出
すべてのメソッドとフィールドで、可能な限り低いレベルのアクセスを実装する必要がありますか？
注意すべき重要なことも。優れた標準のドキュメントは、コードのレビューに大きく役立ちますが、これらの最低限の標準を満たしていますか？
私はこれらのドキュメントの1つに入ることができるものの表面をかろうじて引っ掻きましたが、K.I.S.S。
長く、退屈で、通じないようにしないでください。そうでない場合は、これらの標準に従っていないため、単純にしてください。
このプロセスを何度も行っていました。そして、最も成功した（とにかくでこぼこですが）アプローチは、有名な会社の「コーディング標準」ドキュメントを取得して、ニーズに合わせて修正することでした。
たとえば、私はこれを見つけました： http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf
とにかく、火炎放射器を手元に置いておきます。
乾杯、
彼らは通常小さなものを汗をかき、全体像を無視しようとするので、私はほとんどの標準文書を嫌います。
たとえば、それらのほとんどすべては、変数に名前を付ける方法または角かっこを配置する方法を言います。これは純粋なスタイルであり、開発者コードのグループを正しく支援するためにほとんど何もしません。彼らはディレクトリ構造やコードレイアウトのようなものを無視します。演算子の間に空白をいくつ置くか、メソッドの間に空白行をいくつ置くべきかを正確に伝えている標準文書を見てきました。これらのすべては通常、ルールに大量の例外が発生し、実際にはどれほど無意味であるかを示します。そして、それらは非常に大きいため、誰も追随できません。 。
今、私は多くの異なる人々からのソフトウェアの多くの異なるビットを使用し、それらはすべて異なるスタイルを持っています。私はこれに慣れるだけで、すべての開発グループに共通のスタイルがないことに不満はありません。コードがプロジェクト全体で共通のスタイルである限り、私はそのスタイルが何であるかを本当に気にしません。したがって、すべての標準ドキュメントに対する最初のルールは次のとおりです。プロジェクト内で一貫したコーディングスタイルを維持する。ブラケットがすべて同じである限り、ブラケットの位置にイチジクを付けるべきではありません。宗教戦争を起こして、それらを押してください:)
2つ目はコードレイアウトです。コードを拾ったときに、他の同様の作品と同様の行に沿ってレイアウトされているのを確認したいと思います。 Webサービスがある場合、wsdlコントラクトの名前を明確にしたいのですが、実装の名前を明確にしたいです。私は誰かがファイルとクラスのために真新しくて異なるレイアウトを思いつくことを望んでいません。それは私が迷惑である「コードを捜す」をしなければならないことを意味します。それが私が取り組んだ最後のプロジェクトと同じように見える場合、私は探しているものをどこで見つけるかをすぐに知ることができ、おそらく私が知っている他の人のコードを操作する最大の助けになります。したがって、コードのレイアウト方法の構造を維持（たとえば、ドキュメントのドキュメントフォルダー、インターフェイスのインターフェイスなど-機能するものは何でも、それに従ってください）。
コードアーティファクトも存在する必要があるため、予期されるエラー処理が例外であるかエラーコードであるかを伝える必要があります。 使用中のドキュメントアーキテクチャ機能。また、使用するロギングの種類と、ユーザーにログ/エラー処理を提示する方法、またはコードを実際に管理するために使用されるサブシステムについても説明する必要があります。私はすべてのプロジェクトが異なる方法でログを記録する場所で作業しました。各コードリリースが独自の異なる操作ドキュメントを持っている必要があり、運用担当者にそれが間違っていたかどうかを確認する方法を伝える方法は悲惨でした。イベントログ、ログファイル（この場合）などはすべてここで有効です。同じことがコードの他の一般的な側面にも当てはまります-コードの構成方法（一部のプログラムでは.configファイル、カスタムDB、コマンドラインパラメーター、その他ではレジストリを使用しても意味がありません）。
要するに、重要なのはConsistencyだけです。また、巨大な標準ドキュメントは多すぎて読んだり思い出したりできないので、目に見えないもの（たとえば、ロギングのようなアーキテクチャ標準）を人々に知らせて、現在書いているコードと一貫性を保つように書くように伝えたいと思います。そして、もしあなたがまだコードを持っていなければ、標準文書は必要ありません！ （まあ、あなたがそれを有用にするのに十分なほど書くまでは）。
だから、その要点から：法的文書を作成しようとしないでください、コーディングだけでなく、コードのしくみや、コードが他の人々の期待にどのように適合するかについても考えてください。次に、優れたコードを実行するように人々を信頼します。そうすれば、彼らがそうすることがわかります。 （そして、彼らがあなたと彼らと言葉を持つことができるなら、法律のようにそれを置く必要はありません）。
しないでください、それは時間とエネルギーの全くの無駄です。 StyleCopは素晴らしいものであり、あなたやあなたのチームの誰よりもはるかに経験豊富で賢い人々によって何年にもわたって設立されました。それを受け入れ、愛してください！それはあなたを継続的にガイドします。これは、煩わしい誰かがそれを読むのを待っているどんなドキュメントよりも優れています。