ドキュメントの劣化-対処方法

重要：ソースコードのドキュメントに問題はありません。これは通常のコード監査に属し、最新の状態に保たれます。私たちの問題は、開発者のドキュメント（または、必要に応じて「外部」）、プログラマーからプログラマーへのブログのような小さなヒントです。

ウィキのようなシステムを使用して、プログラマーのドキュメントを作成します。プログラマーのためにプログラマーが書いた記事は、特定のコードがどのように機能するかをもう少し詳しく説明しています。これらのWikiページには通常、次のものが含まれます。

• APIの各部分の設計決定の背後にある動機（たとえば、この特定のサードパーティライブラリがこの方法で何かを行うことを望んでいるため、このotherいことをしました。
• 特定の一般的なタスクを処理する方法の説明（たとえば、適切なアプリケーションスタイルを参照し、レジストリコンポーネントに自分自身を登録し、他のコンポーネントによって自動的に「スキャン」されるために何らかのインターフェースを実装する必要がある些細なポップアップを表示する）
• 良い習慣（主観的なもの、実際にこのようなものを書き留めます）
• 環境設定、必要なツールとそのセットアップ

一般に、主にサイズとブログ投稿/記事のような性質のために通常のコード文書に適合しないコードの記述に関連するもの。

問題

このシステムを導入することは数か月前には良い考えのように思えましたが、最近では解決するよりも多くの問題を引き起こしているように感じます。例えば：

• 人々は記事を書きます...しかし、コードが変更されると、Wikiの更新はめったに続きません
• 急いで誰かが書いたスクラッチ記事の多くは、そのように残しました
• 記事のリクエストは通常​​プロジェクトリーダーからのものですが、正確性や構成についてはほとんど検証されていません。

通常の劣化。コードは変更されましたが、wikiは変わりません。誰かが次に情報を探すとき、彼が通常見つけるのは、時代遅れの低品質のものの束です-そして、何が起こっているのか、彼が見つけたものが正確であるのか、（さらに悪いことに）その一部であるのか疑問に思っています。そして、助けになるはずだったものが、逆になります。

現時点では、プロジェクトリーダーを含め、人々は問題を認識しているようですが、明らかにそれで何かをすることに煩わされる人はいないようです（または、もっと面白いことがあります）。

私の最初の考えは、それをすべて忘却の中に投げ込むことでした（時代遅れの「ヒント」に何回か噛まれた後）。しかし、それは極端すぎるかもしれません。いくつかの情報は注意する価値があり、時々読むことをお勧めしますが、問題は依然として同じです。「最新」にどのように対処しますか？ソースコードに何らかの形でリンクされていますか（したがって、ファイルの更新バージョンがチェックインされると、記事の作成者はコード/記事を修正する必要があるかもしれないと通知されます）？指定された人は、毎日の基本でそれを「見守っていますか」？定期的なクリーンアップを行いますか？

wikiであまりにも多くの雑学を文書化しているようです。

コードのコードブロックとコード内のメソッドを文書化します。多くのコメントを書く必要がないように、コードを自己文書化するようにしてください。単体テストを書くことも役立ちます。

wikiの設計の決定とアーキテクチャをより高い粒度で文書化することで、wikiを頻繁に変更したり、変更するために多くの作業をしたりする必要がなくなります。チームの多くの人々がすでにアーキテクチャを知っていて、チームが急速に成長していない場合、それらを文書化する強力なケースはまったくない可能性があります。

古いコードのように、古い情報をすぐに書き換えたり削除したりすることは、長く残るほど発見するのが難しくなり、より多くの情報が蓄積することです。時間がない場合は、単に削除して、記事に再作業が必要であるとマークを付けると、速度が低下し、とにかくバージョン管理に保存されます。

スクリプトまたはインストールファイルで手順を自動化して手順を文書化します。それ以外の場合はウィキ内に保持しますが、誰かがウィキの手順を使用するたびに、記事を改善するか、プロセスの一部を自動化するように伝えます。

ブログ記事はブログに属します。個人的な意見やアドバイスを共有したい場合は、そのための会社のブログを作成してください。彼らはおそらく彼らの記事が変更されることを望んでおらず、とにかく誰もそれらを変更することはないので、ウィキを雑然とさせないでください。

文書は成果物として扱われるべきであり、したがって、トレーサビリティと受け入れのルールに従い、適切な開発時間を与えられるべきです。

ソフトウェアのドキュメントが「期待」されているのは、そうでない場合でも珍しいことではありません。

根本的だが効果的。誰かが新しいモジュールを書いたが文書化していない場合-課題追跡システムでタスクを再度開き、必要であれば文書化されていないすべてのソースコードを出荷しないようにします。開発者がソースコードのドキュメントを必要な悪として扱うことを許可すると、断片的で古いドキュメントの断片ができあがります。

私の最近のプロジェクトでは、少なくとも必要なすべてのサードパーティライブラリを追跡する傾向があります。誰かが新しいライブラリを導入しても、ドキュメント化されていない場合-ドキュメントが導入されるまでソリューションをロールバックします。このような過激なアプローチがなければ、混乱が生じるでしょう。たとえば、経験のない開発者は、ライセンスがソフトウェアのライセンスと競合するライブラリを使用できます。

何かが急速に変化する場合は、コードの外部で維持するべきではありません。

APIの一部の設計決定の背後にある動機

これは、コードに近づけるために特に重要です。同様に、同じソースファイル内。そうすれば、誰かがファイルに触れるたびに無視するのが少し難しくなり、外部ドキュメントが存在することを知らない人がTheDailyWTFに提出する回数が少なくなります。

通常の劣化。コードは変更されましたが、wikiは変わりません。

ここで、「実行可能なドキュメント」、つまり単体テストが非常に役立ちます。コードが変更され、テストがそれとともに変更されない場合、ビルドは中断します。もちろん、テストをドキュメントとして作成するにはある程度のスキルが必要です。しかし、（良い）外部ドキュメントを書くこともそうです。

問題に対処する良い方法は、それをプロセスの一部にすることです。Wikiの関連ページまでのコードトレースがある/参照している場合、開発者は更新が必要なものを簡単に見つけることができます。さらに、Wikiが（更新に関して）最新であることを確認するために、レビュー担当者にコードレビューを担当させます。

プロセスの一部として追加する別の方法-繰り返しの計画プロセスの一部であるアジャイルモデルを使用しているため、wikiの計画された変更を更新することもできます。wikiは「これが物事の仕組み」リソースとして機能します。

.net言語を使用している場合は、（サンドキャッスル）をご覧ください。XMLドキュメント（C＃の///）を受け取り、MSDNヘルプ形式に変換します。

この形式には説明、コメントが含まれ、コードサンプルやその他の機能を含めることができます。.CHM、.HsX、.MSCH、およびHTML / ASP.NET形式に出力できます。実際のプロジェクトがソリューションに追加され、ビルドサーバーでビルドされます。これを行ってリリースごとにWebサイトに展開しましたが、ドキュメントはリリースに関連し、常に更新されているため、消費者はそれを気に入っています。

また、ドキュメントに含める内容を指定することもできます。現在、2つのプロジェクトがあります。1つは契約と適切なアイテム（クラス、列挙など）のみを含む外部消費者向け、もう1つはプライベートおよび内部フラグ付きアイテムを含むAPIのすべてを含む内部開発者向けです。

これは、APIを使用する動機と癖をドキュメントのコメントセクションに含めることができるため、使用する唯一のドキュメントになりました。このプロセスは、私が働いている場所でうまく機能します。

1）コード。2）ノーコードのメモとドキュメント。

1）コード。

自己文書化するようにしてください。過去に私はそれがしばしば助言されたが、うまく説明されることはめったになかったことを発見した...

この種の擬似コードの代わりに：

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

次のようなコードを実行します。

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

ソース管理を使用して、「誰がいつ何をしたか」情報を追跡します。

2）非コード

この情報を維持するには、wikiおよびマークダウン形式を使用してください。それを仕事の一部にします。それを公表し、投稿し、ブログに載せてください。古いものと新しいものを確認するために、標準の毎週または毎月の会議を設定します。誰かが何かについて尋ねるとき、答えが与えられるというマントラにしてください...「思考は、誰かが次に尋ねるとき、これはウィキにあるべきですか？」