coding-style - コーディング標準をどのように文書化しますか?

Question

コーディング標準を公開する最良の方法は何ですか?またその理由は何ですか?

score 11 · Accepted Answer

コードを使用して標準を文書化します。これは、シニア/リードエンジニアからの施行と相まって、私たちにとって非常にうまく機能しています。実際のドキュメントを維持しない理由は、誰もそれを読んでおらず、すぐに古くなってしまうことが判明したためです。

ポイントを証明するために必要なのは、スタイル/標準を示す既存のコードだけです。

トラベルライト！

score 7 · Accepted Answer

.NETで開発している場合。StyleCopを使用してビルドを確認することをお勧めします。また、ReSharperとStyleCopプラグインを使用することをお勧めします。

ReSharperとStyleCopプラグインを使用すると、コードの下に標準に反する赤い「波状」の行が表示され、マウスを上に置くだけでその理由が説明されます。コードレビューも、maintianへのドキュメントもありません。

ビルドプロセスでStyleCopを使用すると、チェックインされたすべてのコードが標準に準拠していることが保証されます。

score 6 · Accepted Answer

私の意見では、コーディング標準を公開するための唯一の効果的な方法は、開発者が使用する IDE (Eclipse やアイデアなど) に統合することです。そのため、新しいコードはすぐに標準に準拠し、古いコードは ide を使用して再フォーマットできます。

コーディング標準を読む開発者はごくわずかであり、後でそれらを使用する開発者はほとんどいません...

score 5 · Accepted Answer

これは、役立つコードスニペットへのリンクとともに wiki に掲載されています。

次に、このコーディング標準に可能な限り一致するように Eclipse でコードフォーマッタをセットアップしますが、それはベストプラクティスのコーディング方法論には役立ちません。

score 5 · Accepted Answer

スタイルガイドライン - Word 文書または PDF を意味する場合。IMO、これは「石で設定された」ものですが、プロジェクトごとに（機能しないものを見つけた場合は、次のプロジェクトのために修正してください。特にプロジェクトの後半に大量のプロジェクトがある場合は）既存のスタイルに従うコードの）。

score 4 · Accepted Answer

コーディング標準の設定を担当するときはいつでも、自分のニーズに合った適切な標準をインターネットで見つけて使用するようにしています。通常は PDF や Word など、形式は何でも構いません。

車輪を再発明する意味はありません。他の誰かが行った大変な作業を活用することもできます。

score 2 · Accepted Answer

私は誰にでも簡単に応募できるようにあらゆることをしています。

まず第一に、チームの全員がそれらを適用することに同意する必要があります
使用済みエディター（gvim、emacs ...）の設定を共有します
ボイラープレートの見出しを含む空のソースファイルを提供します
標準を1つのリファレンスシートにまとめ、ルールは示していませんが、標準化されたものとして適切にフォーマットされたコードを示しています。

score 2 · Accepted Answer

最良の方法は、Checkstyle を使用してコーディング標準を適用し、checkstyle ルールに反するコードが含まれている場合にビルドが失敗することを保証することだと思います。

その後、コードレビューとペアプログラミングを使用して、後輩が先輩から学べるようにします

wiki ページをセットアップすることもできます。

score 2 · Accepted Answer

現在、上級開発者のみが編集する権利を持つ Wiki にコーディング標準があります。しかし、多くの人がすでに述べているように、最初の数日で誰もそれを読みません。現在、コーディング標準を .NET 側の StyleCop に取り込もうとしているところです。使用する StyleCop のような Delphi フレームワークがないため、Delphi の作業は少し難しくなります。

score 2 · Accepted Answer

以下を使用します。

エディターのツール/プラグイン (checkstyle、pmd、社内ツール)
ビルド時のチェックにより、レポートが生成されます。
wiki は、コードレビューのコメントを文書化するために使用されます
3から、「ツール可能な」ものを社内ツールにリファクタリングします。

score 2 · Accepted Answer

それは状況によって異なります：

私は、開発者が 3 人しかいない小さな会社で働いていました。そこに、私たちはそれを話しました。これは、コーディングスタイルについて疑問がある場合は、共同開発者に尋ねることに他なりません。しばらくして、誰かが同じ質問が何度も出されていることに気付き、私たちの wiki にコーディング標準のページを開きました。

今日、私は小さな研究所で働いています。この特定の分野では、正式なコーディング標準はありません。しかし、チームで作業し、ペアセッションを定期的に行っていると、暗黙のコーディング標準がどこからともなく現れたようです。

航空機誘導用のシステムを開発している何人かの友人から、彼らが以下に基づくコーディング標準に同意していることを知っています。

セキュリティと政府の制限
QA部門からのニーズとインプット
まだ選択の自由がある場合: 開発者からの入力

このコーディング標準は書き留められており、QA によって施行されています。

score 2 · Accepted Answer

コーディング標準を文書化するために、次のことを行いました。

それらをプレーンなワードファイルに書き留めました。このスタイルガイドのベースは、Sun コーディング規約です。
これらのコーディング規則に従うように Checkstyle と PMD を構成し、さらに、定義された Checkstyle と PMD 構成に適合する適切な構成を持つ Eclipse のデフォルトワークスペースを提供しました。
各アーキテクトがスタイルガイドと Checkstyle、PMD、および Eclipse の構成を変更できるように、どの Checkstyle、PMD、および Eclipse 構成がスタイルガイドのどの部分を満たすかを説明するコーディング規約に 3 つの章を追加しました。
Checkstyle と PMD をプラグインと一緒にインストールすることで、Checkstyle と PMD によって定義されたコーディング規則がデフォルトになり、簡単に選択できるように、小さなプラグインを開発しました。

書き留めるだけでなく、開発環境に統合することは非常に役立つと考えています。一方で、これは Eclpise に対してのみ行っています。これは、地球上のすべての IDE に対してそれを行うには多すぎるためです。

score 1 · Accepted Answer

Eclipseを使用している場合は、フォーマッター（[設定]-> [Java]->[コードスタイル]->[フォーマッター]）を使用して、ソースファイルの保存時にコードを自動的にフォーマットできます。ウィキで会社のフォーマッターを利用できるようにして、誰もがそれをEclipseにインポートします。

フォーマッターの優れた点は、使用するフォーマッターを決定できるため、さまざまなフォーマットでさまざまなプロジェクトを作成できることです。ただし、通常は1つの形式のみを使用するため、コードはすべてのプロジェクトで統一されています。

score 1 · Accepted Answer

コード標準を次のように文書化します。

最も重要な一般的なスタイルからの構造 (インデント、行の折り返し、波括弧など)
(あまり目立たない詳細 (または前後のスペース))
コード例
Eclipse コード・フォーマッターを構成するための設定の説明
プロサ

score 1 · Accepted Answer

私が小さなチームを管理していたとき、私たちの「コーディング標準」は、コードをチェックインするときに (チーム全体の rc ファイルで) インデントを実行する CVS 上のラッパースクリプトでした。

score 1 · Accepted Answer

変更の管理に使用されるSVNを使用した社内Webサイトが機能します。「最新」は常にオンラインでチームに提供されます。

score 1 · Accepted Answer

私たちのプロジェクトはほとんどが python で書かれているので、基本的にはPython コーディングガイドラインを参考にして、あちこちで気に入らないところを変更し、Trac wiki に貼り付けました。開発者がどこにあるかがわかるように、フロントページにリンクされています. これまでのところ、実際にフォローされているというかなりまともな仕事をしています!

score 1 · Accepted Answer

コードガイドラインは、プラクティスを説明する全社的な文書です。そしてそれは利用可能であり、非常に厳密に従う必要があります.

コードの書式設定基準は、チーム (またはプロジェクト) メンバー間で決定されます。私たちのプロジェクトでは、 Resharperプラグインの設定のセットとして SVN に保持されています。

score 1 · Accepted Answer

最初のプロセスでは、小見出しを用意した wiki がさまざまな開発者から意見を収集するのに役立ちます。フィードバックが収集されると、整理して「公開」することができます。

アップデート：

数年後、Google Docs は一種の wiki として機能するようになりました。

score 1 · Accepted Answer

扱いにくく、時代遅れになりがちであることが判明したWord文書から、

標準と例を含む Wiki ページ
CI プロセス中に実行される自動コーディング標準検証ツール

NBまた、CI サイクルでビルド自体以外の実行を使用しないクライアントもいます。彼らはルールを ReSharper に保持し、結果に非常に満足しています。

coding-style - コーディング標準をどのように文書化しますか?

20 に答える 20

Related

Reference