コーディング標準には何が必要ですか?[閉まっている]


34

良い(読む:役に立つ)コーディング標準には何が必要ですか?

  • コードに必要なもの。
  • コードにあるべきではないもの。
  • コーディング標準には、言語、コンパイラ、またはコードフォーマッタが実施するものの定義を含める必要がありますか?
  • 循環的複雑度、ファイルごとの行数などのメトリックについてはどうですか?

回答:


40

すべての要件の理由。このように、標準に従うことはある種のカーゴカルトにはならず、人々は、その理由がもはや適用されない場合は標準を変更するか、または理由が明らかに適用されない特定のケースで標準に違反することは問題ないことを知っています。


3
絶対に。標準のすべての項目には、根拠を明示的に指定する必要があります。
AShelly

4
選択する正当な理由がない場合もありますが、誰もが同じことをすることが望ましいです。車のアナロジーを使用するために、私たち全員がなぜ右側を運転するのかわかりませんが、右側の半分と左側の半分よりはるかに優れています。
デビッドソーンリー

9
@David:それがコーディング標準を持っている完全に正当な理由です。それが理由である場合、それは単にそのようなもの、すなわち「理由:コードベースの一貫性を改善するために」と述べられるべきです。
dsimcha

実際、コーディング標準について最も重要なことは、コーディング標準があるということです何が本当に二次ありです。
ヨルグWミットタグ

20

タブ対スペース!同僚の1人が誤って多くのタブをリポジトリにシフトするスペースにコミットすると、更新が狂ってしまいます


1
心から同意します!
マティアシュ

2
私見、それはコーディング標準に値する唯一のものです。
P


2
私見、それはコーディング標準カバーすべきでないものの優れた例です。
Bjarkeフロイント・ハンセン

@bjarkef、タブとスペースが混在したコードが好きですか?
ジェキュー

19

命名規則

編集:これにより、命名規則ではなく、ガイドラインの命名を意味します。

たとえば、ガイドラインはになりますAll boolean values should begin with Is/Can/Has/etc when possible。ルールはAll boolean values must start with Is


3
LPSZ * lppsz_CPP_MrKim_ClassOfStudents [] [];
Mateen Ulhaq

3
-1:これはまさに開発者が標準を無視するような低レベルの詳細です。全員にネクタイを着用するように命じることもできます。
TMN

2
@TMN:命名規則の欠如は、開発者にコードの理解を絶望させる正確な種類のものです。それらは厳選する必要はありませんが、いくつかの一般的なガイドラインが非常に役立ちます。
デヴィッドソーンリー

1
@レイチェル:ええ、「すべてのブール型プロパティは「Is」で始まる必要があります」という標準がありました。IsCanUpdateやなどのプロパティで終了しますIsHasChildren。確かに、それは間違っていますが、標準で定められています。そして、これが私のポイントです:これらのことを指定し始めたら、すべてのベースをカバーするか、そうでなければ標準がカバーしないか、ひどくカバーする何かにぶつかってから、間違ったものを書くか、または、標準を無視し始めます。どちらにしても、チームは負けます。
TMN

1
そのため、オブジェクトの命名方法については、ルールではなくガイドラインを含めるべきだと思います。正確な名前はまだ開発者に任されています。答えを編集します。
レイチェル

10

グループのコーディング標準には、対処する必要がある警告およびエラーのコンパイラオプションを含める必要があります。

プログラマーは自分のコードの警告を自由に増やすことができますが、他の誰かのコードを読んで作業することでコンパイラーから得られる出力が乱雑にならないようにベースラインが必要です。

そのような標準は、そうでなければ適合しない例外的なコードが存在する場合、プログラマがそのような警告を個別に無効にする方法にも対処する必要があります。


同意した。私が追加する他の部分は、警告としてそれを生きたままにする場合、それを変更するか警告を抑制することによって対処する必要があるということです。そうしないと、警告は役に立たないほど速くなり(大規模なプロジェクトでは多すぎる)、警告を停止することもできます。VSでは、警告がビルドを壊し、それらに対処するように強制するのを見るのが好きです。
MIA

これは、標準ではなく、メイクファイルに入れるべきものではありませんか?
Bjarkeフロイント・ハンセン

@bjarkef:最終的にオプションはMakefileに入ります。しかし、それを標準に入れることのポイントは、対処しなければならないものを標準化することです。たとえば、開発者は常にシリアル化IDを作成する必要がありますか?これを義務付けるか無視するかを決定するのはチーム次第です。
マクニール

@bjarkef:もちろん、しかし、新しいプロジェクトを開始し、新しいメイクファイルを作成する必要がある場合(または、新しいプロジェクトがビルドツールにMake以外の何かを使用する場合)の標準リファレンスにそれらを含めるとよいでしょう。
TMN

9

私が好きないくつかの標準(私はそれらがたくさんあることを知っていますが、それは私が好むものです):

  • 80%のユニットテスト範囲
  • コードの共同所有権(コンパイラではなく、チームメイトが読み取るコードを記述します)
  • コメントを書いてください。新人に言うことを書いてください。
  • 複雑にしないでおく

単体テストのカバレッジに関する要件は、コーディング標準に入ることができる最も優れたものの1つです。
アダムクロスランド

テストカバレッジについて:なぜ80%しかありませんか?これは、80/20ルールの例でもありますか。あなたの経験では、最終的な20%が達成するのに100%の努力が必要になるでしょうか。また、どのような報道ですか?[例えば、声明の範囲?機能カバレッジ?決定カバレッジ?条件カバレッジ?]
マクニール

@Macneil:はい、そのようなものです。80%はほとんどのクラスにとって「十分」であり、良い数であることがわかりました。私はかつて95%を達成しようとしましたが、それは時間の無駄です。もちろん、それはいくつかのクラスのために100%を達成するのは簡単だ場合は、先に行く

それで、その声明の範囲は?多くのツールはそれ以上のものを提供しないようです。どのツールを使用していますか?
マクニール

私はそれを建てnCoverでTestDriven.netを使う

7

規格は、あなたがコードを最初に書いている少しを助けるコーディング、彼らは助ける多くの あなた、またはあなたの交換は、2年後にコードを更新する必要があります。

理想的な標準は、コード内の任意のページにジャンプし、最初の読み取りで何をしているのか正確に理解できるコードにつながります。

  • 名前は、どのデータが操作されているかを明確に説明します。
  • 中括弧は制御の流れを明確にし、
  • コメントは、非自明なアルゴリズムなどを説明します。

一方、arbitrary意的な標準が多すぎると、コードの記述の流れが混乱する可能性があります。ですから、提案されたコーディング規約のすべての項目は、次の2つの基準に対して評価されるべきだと思います。

  • このルールは、コードが 正しいますか?
  • このルールは、コードがクリアであることを確認するのに役立ちますか?

どちらも当てはまらない場合、アイテムは任意であり、おそらく不要です


私が書いた標準には、次のものを含めます。

明確にするために:

  • ファイル構成:ファイル内のアイテムの固定順序を指定すると、チームは他のファイルを簡単にナビゲートできます。#definesや構造定義を見つけるために狩りをする必要はありません。

  • 命名規則:一貫性のある命名により、読みやすくなります。ただし、過度に多くのルールを指定しすぎないようにしてください。これにより、書き込み可能性が損なわれます。

  • コード構造。中かっこの配置、インデントレベル、スペースとタブなど チームに最適なオプションを見つけて、それを守ります。

正確さのために:

  • 問題の種類に固有のベストプラクティス:メモリの割り当て、同時実行、または移植性に関するルール。

  • 「定数の正確性」、staticおよびの適切な使用volatileなど。

  • プリプロセッサマクロ、およびその他の簡単に悪用される言語の機能に関するルール。


6

人々が考えることを止める否定的な制限ではなく、人々を考えさせる、刺激的で実用的なアイデア。

それ以外の場合、バナナの後に行くことを恐れているコードモンキーを取得します。


4

コーディング標準には何が必要ですか?出来るだけ少なく。もっと少なく。そして正当化してください。

私はプロセスを必要としないカウボーイコーダーだからではなく、(おそらく)「おそらく'95年のどこかのネットでこれを見つけた」以上のロジックのない重いコーディング仕様を見たからです働く官僚的な悪夢。

一部の人々は、標準を上げていくと、コードの「品質」が向上し、おそらくその尺度が上がると信じているようです。それまでは、アーキテクチャ、パフォーマンス、常識、およびファイル内の行数よりも重要な他の多くのものを無視します。


3

標準を実施するためのコードレビューの手順。ああ、バグも見つけます。


3

いくつかの古き良き常識は見過ごせないでしょう。関係のない点(フォントの種類やサイズなどの項目は、私が見た中で最も極端なものの1つである)に労力を費やしているコーディング標準文書が多すぎます。

開発者グループにいる場合の最善の方法は、お互いに話し合ってコードを確認し、容認できるものについてコンセンサスを形成し、ガイドラインとして主要なポイントを書き留める必要があるが、まさにそのガイドライン。ガイドラインとの相違を正当化できない場合は、なぜそれを行っているのかを検討する必要があります。

結局のところ、明確で理解可能なコードは、レイアウトやタイポグラフィに関する厳格なルールよりも重要です。


フォントの種類とサイズはどのように確認されますか?
ジェキュー

@xepoch、それは視覚的にその時点でした。その当時の標準になった理由は2つあり、印刷されたときにマネージャーが読みやすく、書体がスペースの問題を修正するように指定されていたため(モノスペースが要求された)、文字の各列並んでいます。
GrumpyMonkey

oh lord-すべての間に空行の数を義務付けたstdを思い出させます-私が満足しているメソッド間(多くの空白が大きなブロックを区別するのに役立ちます)が、すべてのコメントブロックの前後、およびfn宣言の後関数コードなどの前に...最後に少しばかげている。
gbjbaanb

2

他の人が述べたように、コードテストのカバレッジは重要です。私も見たいです:

  • プロジェクト構造。テストはコードの一部ですか、それとも別のプロジェクト/パッケージ/ディレクトリにありますか?UIコードはバックエンドのものと一緒に動作しますか?そうでない場合、どのように区分化されますか?

  • 開発工程。コードの前にテストを書きますか?壊れたビルドの修正は開発よりも優先されますか?コードレビューはいつ行われますか?

  • ソースコード管理。何時にチェックインされますか?設計ドキュメントとテスト計画は改訂管理されていますか?いつ分岐し、いつタグ付けしますか?以前のビルドを維持しますか?

  • 展開標準。ビルドはどのようにパッケージ化されますか?リリースノートには何が必要ですか?アップグレードスクリプトはどのように作成/制御/実行されますか?

命名規則、書式設定、および関数/メソッド/モジュールに含めることができる行の数についてのくだらないことはすべて忘れてください。1つのルール:既存のスタイルが編集中のすべてのものを使用します。誰かのスタイルが気に入らない場合は、コードレビューでそれを選択してください。唯一の例外はtabs-vs-spacesの場合です。これは、多くのエディター/ IDEが盲目的​​に一方を他方に変換し、すべての行が変更されたために変更履歴が破棄されるためです。


2

実際に対処する必要があるのは2つあると思います。同じ方法でアプローチすることはできないため、実際にはそれらを別々に検討しますが、両方とも重要だと思います。

  • 技術的な側面:危険なコードや不正なコードを回避することを目的としています(コンパイラー/インタープリターが受け入れた場合でも)
  • プレゼンテーションの側面:プログラムを読者に明確にすることに関係している

私がコーディング標準の資格を得る技術的側面は、ハーブサッターアンドレイアレクサンドレスクC ++コーディング標準と同様です。コーディングスタイルの資格があるプレゼンテーション命名規則、インデントなどを含む

コーディング標準

純粋に技術的であるため、コーディング標準はほとんど客観的です。そのため、すべてのルールは理由によってサポートされる必要があります。私が各アイテムに言及した本では:

  • タイトル、シンプルで要点
  • タイトルを説明する要約
  • 議論。それ以外の場合の問題を示し、そのため理論的根拠を述べる
  • オプションのいくつかの例、良い例は千の言葉の価値があるので、
  • オプショナルこのルールを適用できない例外のリスト。回避策がある場合があります
  • この点について議論した参考文献(他の書籍、ウェブサイト)のリスト

理由と例外は、理由と時期を要約しているため、非常に重要です。

タイトルは、レビュー中に作業するタイトルのリスト(チートシート)を持っているだけで十分であるように明確にしなければなりません。そして明らかに、アイテムをカテゴリ別にグループ化して、探しやすいようにします。

SutterとAlexandrescuは、C ++が毛むくじゃらだと見なされているにもかかわらず、わずか100項目のリストしか持っていませんでした;)

コーディングスタイル

この部分は一般的に客観的ではありません(そして完全に主観的です)。ここでの意図は、一貫性を保証することです。これは、メンテナーや新規参入者を支援するためです。

ここでは、インデントまたはブレースのスタイルが優れているという聖戦に参加したくないため、このフォーラムがあります。したがって、このカテゴリでは、コンセンサス>多数決>リーダーによるarbitrary意的な決定によって物事を行います。

書式設定の例については、芸術的スタイルのオプションのリストを参照してください。理想的には、プログラムがコードを書き直すことができるように、ルールは明確で完全でなければなりません(ただし、コードをコーディングすることはまずありませんが;))

命名規則については、クラス/タイプを変数/属性と簡単に区別できるようにします。

このカテゴリでは、次のように「対策」を分類しています。

  • 短い方法から長い方法を好む:通常、長い方法について合意するのは難しい
  • インデントを減らすために、早期復帰/継続/中断を好む

その他?

そして最後の言葉として、コーディング標準で議論されることはめったにありませんが、おそらくそれは各アプリケーションに固有であるため、コード編成です。建築上の問題はおそらく最も顕著な問題であり、最初の設計を台無しにしてしまい、今から何年も悩まされることになります。おそらく、基本的なファイル処理のセクションを追加する必要があります。パブリック/プライベートヘッダー、依存関係管理、懸念の分離、他のシステムまたはライブラリとのインターフェース...


しかし、それらが実際に適用および実施されなければ、それらは何もありません。

コードレビュー中に違反が発生する必要があります。違反が未解決の場合、コードレビューは問題ありません。

  • ルールに一致するようにコードを修正します
  • コードが目立たなくなるようにルールを修正します

明らかに、ルールを変更することは、リーダーから「先に進む」ことを意味します。


2

私は、フレームワーク設計ガイドラインの形式が好きです。これには、ガイドラインの一般的なセクションと理論的根拠が含まれています。最も有用な部分は、Do、Do Not、Avoid、Considerで始まる詳細です。

以下は、インターフェイスメンバを明示的実装するセクションの例です。次の項目があります(説明のために理論的根拠を削除しました)。

避ける強い理由がない限り、明示的にインターフェイスメンバー実装することは

メンバーがインターフェイスを介してのみ呼び出されることを意図している場合は、インターフェイスメンバーを明示的に実装することを検討してください

明示的なメンバーをセキュリティ境界として使用しないでください

機能が派生クラスによって特殊化されることを意図している場合、明示的に実装されたメンバーと同じ機能を提供する保護された仮想メンバーを提供してください

これにより、一般的なトーンが作成されます。回避と検討を使用すると、開発者が自分の判断を使用できるようになります。また、ルールではなくガイドラインであるため、開発者はそれらをより口当たりがよく、順守する可能性が高くなります。


私が現在働いている場所では、すべてのインターフェースを明示的に実装する必要があり、それは大きな苦痛です。コーディング標準を作成する前に、フレームワーク設計ガイドラインを読んでいた場合のみ。
マーティンブラウン

1

誰もセキュリティについて言及していないようです-コーディング標準では、安全なコード要件(たとえば、入力検証モジュールの使用、strcpyなどの既知の脆弱な機能の禁止、エラー処理要件など)への参照が必要です。


+1:経験豊富な開発者であっても、このこととマルチスレッドに関する考慮事項は不明または誤解されていることがよくあります。
TMN

1

例。すべてのルールを使用する、きちんと配置された、自明ではない、現実に近い例。コメント(必ずしもコードの一部ではない)例のどの部分がどの規則に従うか。

テンプレート。C ++の種類ではなく、コピーアンドペーストしてライブで満たすもの。コピー元の参照がある場合、24行の定型コメントを簡単に取得できます。


1

ナンバーワン機能:絶対最大2ページ。

これは、すべての開発者に読んで覚えてもらいたいものです。新しい関数を書く必要があるたびに(またはさらに悪いことに新しい行を書く必要があるたびに)標準を調べる必要はありません。そのため、短くして、最終製品の価値を実際に高めるルールのみを守ってください。


1

コーディング標準は実際にはいくつかの項目です。

コーディング規約

  • これらのことは、exの「コードベースの一貫性」以外の理由を必要としません。プライベートメンバー変数で「_」を使用するかどうか。
  • いくつかの正しいアプローチがあります。一貫性を保つために1つだけ選択する必要があります。例えば 例外またはエラーコードを使用してエラーを処理します。

ベストプラクティス

  • これらの項目には、明確な例とともに常に正当な理由が必要です

例えば 試した後に空のキャッチを残さないでください

try { Foo(); } catch { //do nothing }

1)Foo()によってスローされた例外がある場合、後続の関数でfooが成功したと見なされる他の問題が発生する可能性があります。

2)グローバルエラーハンドラーは、prodで発生した例外をサポートチームに通知しません

  • Assertsを使用して仮定をテストするなど、「Defensive Coding」のプラクティスをカバーしています。

コーディング環境

  • チーム全体が使用するツール。例えば VS 2010、Resharper、Kilnなど。

0

コーディング標準は、紙に書かれた場合、非常に効果的です。Goのコーディング標準の公開方法が気に入っています。gofmtプログラムのテキストをフォーマットにフォーマットするツールがあります。コーディング形式に関する議論は、単にソースのパッチとして行われますgofmt

フォーマットに必要なものについては、

  • 変数、マクロ、定数、リテラル、関数などの命名方法
  • {、}、(、)、[、]の配置方法 if、関数本体、他の目的のステートメントブロック、
  • くぼみの幅
  • テキスト行に許可される文字数
  • リファクタリングのためにコードが拒否/送信されるまでに許可されるインデントのレベル数
  • リファクタリングのために送り返される前に関数ごとに許可されるコードの行数
  • 関数がリファクタリングのために送り返される前に取ることができる引数の最大数
  • ボディが画面上のコードの1ページを超える場合、関数が何をするかを簡単に説明し始める前の数行のコメント。オブジェクトの達成方法を関数の本体のコードに任せる

他の(主にC言語)コードを読んでいるときに、変数/関数名がプロジェクトのコンテキストで直感的でない場合、または5レベルのインデントを超える場合、または関数が6つまたは7つ以上の引数をとる場合、または関数が繰り返し実行される場合画面に2〜3ページあると、コードを読んで理解することが非常に難しくなります。拡張/保守作業を行うように求められた場合、それは難易度を高めるだけです。gofmtすべてのプロジェクト(または言語)でプログラムを作成し、プロジェクトにコミットする前にすべてのソースコードファイルをそのプログラムで実行するように願っています。


長年にわたってコードの美化が行われてきました。あなたの言語に合わせてグーグルを探してください。
gbjbaanb


弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.