java apiなど、十分に文書化されたコードの良い例がいくつかあります。しかし、gitや企業の内部プロジェクトなどの公共プロジェクトの多くのコードは十分に文書化されておらず、あまり初心者には適していません。

すべてのソフトウェア開発スティントで、文書化が不十分なコードを処理する必要がありました。次のことに気づきました-

  1. コードにコメントがほとんどまたはまったくありません。
  2. メソッド名と変数名は自己記述的ではありません。
  3. コードがシステムまたはビジネスプロセスにどのように適合するかについてのドキュメントはほとんどまたはまったくありません。
  4. 悪い開発者を雇うか、良い開発者を指導しない。シンプルでクリーンなコードを書くことはできません。そのため、開発者を含む誰もがコードを文書化することは困難または不可能です。

その結果、私は多くのことを経験しなければなりませんでした。コードを書いて、多くの人と話して物事を学びます。これはみんなの時間を無駄にしていると思います。また、プロジェクトへの新規参入者のためのKT /知識移転セッションの必要性も生み出します。

次の理由により、ドキュメントにふさわしい注意が払われていないことを学びました。

  1. 怠惰。
  2. 開発者はコード以外のことをするのが好きではありません。
  3. 仕事のセキュリティ（誰もあなたのコードを簡単に理解できない場合、あなたは簡単に置き換えることができないかもしれません。）
  4. 締め切りが難しいと文書化する時間がほとんどありません。

それで、会社やプロジェクトで優れた文書化の実践を奨励し、実施する方法があるかどうか疑問に思います。戦略は何ですか。複雑さに関係なく、プロジェクトのシステムとコードの適切なドキュメントを作成するために使用されますか？ドキュメントが最小限または不要な場合の良い例はありますか？

IMHO、私たちは持っているべきだと感じていますプロジェクトが提供された後のドキュメントレビュー。それが単純、簡潔、例示的でユーザーフレンドリーでない場合、開発者または技術ドキュメントエンジニアがその責任を負い、修正する必要があります。人々が大量のドキュメントを作成することも期待していません。頭の最初の本のようにユーザーフレンドリーになることを望んでいませんが、何時間もの分析と無駄なKTセッション。

この狂気を終わらせる、または軽減する方法はありますか？ 「ドキュメント駆動開発」かもしれませんか？

コメント

  • 適切なドキュメントがないことが多いもう1つの理由があります。それは、適切なドキュメントを作成するのが非常に難しいことです。'コードを英語で言い換えるだけでなく、コードがそのように設計/記述されている理由について説明します。この情報の必要性は、書き留めておくべきだった後の数か月後に明らかになります。
  • もう1つの重大な理由：多くの開発者は第二言語として英語を使用している、および/または英語をひどく書いています。 。メソッドのワンライナーを書くように強制することもできますが、優れたドキュメントが必要な場合は、その費用を支払う準備をして、専門家に依頼してください。

回答

コードを文書化する方法

すでにヒントがあります：JavaAPIがどのように文書化されているかを見てください。

より一般的には、すべてのプロジェクトに適用される固有のルールセットはありません。私がビジネスクリティカルな大規模プロジェクトに取り組んでいるとき、ドキュメントは私が小さなオープンソースライブラリ用に書くものとは何の関係もありません。それは私の中規模の個人プロジェクトのドキュメントとは何の関係もありません。 。

多くのオープンソースプロジェクトが十分に文書化されていないのはなぜですか？

ほとんどのオープンソースプロジェクトは、楽しいためにそれらのプロジェクトに貢献する人々によって作成されているためです。ほとんどのプログラマーと開発者はドキュメントを書くのは楽しいものではありません無料で行うことができます。

なぜ多くのクローズドソースプロジェクトがありますか十分に文書化されていませんか？

（1）優れた文書を作成し、（2）それを維持するのに莫大な費用がかかるためです。

  1. 即時コスト（ドキュメントの作成コスト）は、関係者にはっきりとわかります。チームがプロジェクトのドキュメント化に次の2か月を費やすように依頼した場合、さらに2か月分の給与を支払う必要があります。

  2. ロー長期的なコスト（ドキュメントを維持するためのコスト）は、管理者にとっても非常に簡単に気付くようになり、コストを下げたり、遅延を短縮したりする必要がある場合の最初のターゲットになることがよくあります。これにより、古いドキュメントの追加の問題が発生し、すぐに役に立たなくなり、更新に非常に費用がかかります。

  3. 長期的な節約（探索に数日を費やす必要がないための節約）一方、何年も前に文書化されるべきであった基本的なことを理解するためだけのレガシーコードは、測定が困難であり、文書の作成と維持は時間の無駄であるという一部の管理者の気持ちを裏付けています。

私がよく観察するのは、次のとおりです。

  1. 最初は、チームは多くのことを文書化する用意があります。

  2. 時間の経過とともに、締め切りのプレッシャーと関心の欠如により、ドキュメントの維持がますます困難になっています。

  3. 数か月後で、プロジェクトに参加する新しい人は、実際のシステムにまったく対応していないため、ドキュメントを実際に使用できなくなります。

  4. それに気づき、経営陣は開発者を非難しますドキュメントを維持していないため。開発者はそれを更新するのに数週間を費やすように求めます。

    • 管理者がそのために数週間を許可した場合、サイクルが繰り返されます。

    • 以前の経験に基づいて経営陣が拒否した場合、製品にはドキュメントがないため、悪い経験が増えるだけですが、作成と保守に数か月が費やされました。

ドキュメントは、テストと同じように継続的なプロセスである必要があります。数千のLOCをコーディングするだけで、1週間を費やすだけで、テストとドキュメントに戻るのは非常に苦痛です。

チームに書き込みを促す方法ドキュメント？

クリーンなコードの記述、定期的なリファクタリング、デザインパターンの使用、または十分な単体テストの追加を促す方法と同様です。

  • 模範を示してください。優れたドキュメントを作成すると、ペアもそれを開始する可能性があります。

  • ドキュメントの検査を目的とした正式なコードレビューを含む、体系的なコードレビューを行います。

  • チームの一部のメンバーが優れたドキュメント（またはドキュメント）に特に反感を持っている場合は、その主題について非公開で話し合い、より優れたドキュメントを作成する上での障害を理解します。彼らが時間の不足を非難している場合は、問題の原因がわかります。

  • ドキュメントの存在または欠如を数週間または数か月間測定可能にしますが、そうしないでください。たとえば、LOCごとのコメントの行数を測定することはできますが、それを永続的な測定にしないでください。そうしないと、開発者は、低いスコアを取り除くためだけに、長くても意味のないコメントを書き始めます。

  • ゲーミフィケーションを使用します。これは前のポイントと一緒になります。

  • 正/負の補強を使用します。

  • （ SJuan76によるコメントを参照）コメントの欠如をエラーとして扱います。たとえば、Visual Studioでは、XMLドキュメントを生成するオプションを確認できます。すべての警告がエラーとして扱われることも確認すると、クラスまたはメソッドの先頭にコメントがない場合、コンパイルが停止します。

    前の3つのポイントについては、これを使用する必要があります。慎重に。私はしばらくの間、特にタフな初心者プログラマーのチームでそれを使用しましたが、最終的には次のようなStyleCop準拠のコメントになりました：

  /// <summary> /// Gets or sets the PrimaryHandling. /// </summary> public Workflow PrimaryHandling { get; set; }

これは、特に役に立ちませんでした。

覚えておいてください：プログラマーがあなたを台無しにしたいときに、自動化されたものは悪いコメントを特定するのに役立ちません。コードのみレビューやその他の人間のタスクが役立ちます。

ドキュメントが最小限または不要な場合の良い例はありますか？

アーキテクチャと設計を説明するドキュメントは必要ありません：

  • プロトタイプの場合

  • タスクを完了するために数時間で作成された個人プロジェクトの場合、このプロジェクトはこれ以上維持されないことを確信しています。

  • 明らかなプロジェクトの場合、サイズが小さいことと、特にクリーンなコードが相まって、将来のすべてのメンテナがコードを探索するよりもドキュメントの作成に多くの時間を費やすことになります。

コード内のドキュメント（コードコメント）は、コードが自己ドキュメント化されている場合、一部の開発者によると必要ありません。彼らにとって、コメントの存在は、まれなケースを除いて、良い兆候ではありませんが、コメントを必要とせずにコードが明確になるほどリファクタリングされていないことを示しています。

プロジェクトの納品後にドキュメントのレビューが必要だと思います。

プロジェクトが納品された場合週に一度、それは行く方法です。プロジェクトがアジャイルではなく、6か月の間隔で配信される場合は、より定期的なレビューを行ってください。

コメント

  • ' 'を奨励する方法については、多くのIDEでドキュメントの欠落を警告として通知できることを付け加えておきます。あるいは、ドキュメントの静的分析をOSBで実行できる場合もあります（もちろん、それだけでは十分ではありません）。
  • @ SJuan76：確かに。 Visual Studioは、コメントの欠如をコンパイル時エラーとして扱うこともできます。回答を編集して、それに関するメモを追加しました。
  • @ ArseniMourzenko-ドキュメントのストーリーを追加することで、アジャイルでいくつかのドキュメントを奨励できることを読みました。ただし、これらは他のストーリーをブロックしてはなりません。つまり、他のストーリーの定義が完了し、ドキュメントストーリーの完了を含めてはなりません。それはどのように聞こえますか？
  • @ ArseniMourzenko-I 'あなたの答えにさらに2つのポイントを追加したいと思います。 （1）Jiraなどでは、常にドキュメントのタスクを追加します。 （2）さらに2人がレビューしたドキュメントを&タスクとして配置します。そうすれば、&を文書化するように通知され、低品質の文書を作成することを回避できます（レビューのため）。 '優先順位を付けない&レビューすると、問題が発生します。 Amazonが多くのドキュメント&ドキュメントレビューを行っていることを知っています。多分少し多すぎます。

回答

コメントとドキュメントを区別する必要があると思います。コメントは説明的ですが、一貫性に欠け、コード全体に散らばっています。コメントは、自己記述が不十分なコードを補うものであってはなりません。代わりに、他のプログラマーに注意が必要な部分を示唆する必要があります。

コードを文書化するかどうかは、プロジェクトの規模によって異なります。確かに、すべてのを文書化する必要があると信じている人がいます。誰が反対するのか、その考えを正当化するのは簡単なようです。知識を文書化する？幸いなことに、ソフトウェア開発は科学ではなく、小さなプログラムの背後にある詳細が不明瞭になっても世界は崩壊しません。多くの開発者が使用するプロのソフトウェアに関しては、もちろんコードを文書化する必要があります。そのレベルでコーディングするなら、あなたは明らかにそれを知っているでしょう。

tl; dr

すべてのプロジェクトを十分に文書化することを求めているなら、あなたはあまりにも多くを求めています。 。

コメント

  • Fortunately software development is not scienceこれを信じる理由について詳しく教えてください。
  • @ Borat-ソフトウェア開発はエンジニアリング分野であり、科学によって提供されるツールを使用することを意味します。
  • すべてを文書化するよう求めているわけではありません。システムとコードの機能の概要を説明するのに十分です。たとえば、テレビの使用方法を教えてください。' LCD、CRT、仕事を成し遂げるための真空管またはソリッドステートデバイス。修理担当者がその情報を必要としている場合は、別のドキュメントを作成してください。
  • 高レベルの概要が必要な場合は、識別子名で十分です。テレビのボタンに"オン"のラベルが付いているのと同じです。したがって、低レベルの詳細を求めています。
  • @LeopoldAsperger：Boratは、クラスのメソッドではなく、アーキテクチャと設計の文書化について話していると思います。

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です