アプリケーションのソースコードに新しいプログラマー向けの適切なドキュメントがあることを確認するにはどうすればよいですか？
可能性のある複製：
どのくらいのドキュメントで十分ですか？
IBM、Microsoft、またはgoogleのような大規模IT企業が、彼らのアプリケーションソースコードに将来の新しいプログラマーのための適切なドキュメントがあることを確認する方法を知っていますか？彼らの方法やテクニックは何ですか？彼らはプログラマにドキュメントを書くように言うか、それを行うために専門のテクニカルライターを雇うべきか？文書は別のファイルまたはソースコード自体（注釈/コメントの形式）にありますか？それとも私が知らない別の方法ですか？
私の経験では、（私の国の）IT企業のほとんどが、アプリケーションドキュメント作成ライティングカルチャーを課すのが非常に怠惰であることを知っているので、お願いします。そのため、新しいプログラマーが来ると常に問題が発生します。彼は常に、ドキュメンテーションなしでソースコードの大きなチャンクを読んで学ぶように指示される状況に直面します。もちろん、彼は上級プログラマに彼に説明するように頼むことができますが、時には上級プログラマが仕事に忙しすぎて彼らがしぶしぶあなたを助けたいと思っていることもあり、時にはコードを理解している唯一のプログラマがすでに辞任していることはさらに悪いことかもしれません。したがって、ソースコード:(。
プログラマーの仕事はコーディングとテストのセッションで既に面倒で面倒なので、コメントやドキュメントを書くプログラマーの怠惰さをどういうわけか理解できます。常に遅れをとっている締め切りのベルや怒っているボスについては触れないでください。プログラマーがコードタイピングの長いセッションを終えた後、ドキュメンテーションのためにもう一度タイプしなければならないときに、プログラマーにとってどれほど苦痛で疲れるのか想像できません。
テクニカルライターにとって、私は彼らとの経験がありませんでした。ソースコードを完全に理解しているのはプログラマー自身なので、テクニカルライターがいかに役立つか疑問です。その場合、プログラマーはテクニカルライターに同行してソースコードを説明する必要があります。
注：私が話しているのは、システムアナリストまたはビジネスアナリストがより適切に記述したユーザードキュメント/ガイドではなく、ソースコードまたはアプリケーション開発ドキュメントです。開発ドキュメントには通常、アプリケーションの開発に関する技術情報（アプリケーションの機能、クラス/関数リファレンス、クラス関係図、データベース情報、ネットワーク情報など）が含まれています。ユーザードキュメントは、アプリケーションのハウツー情報に関する詳細です-ユーザー。
残念ながら、ソースコードを「適切に」文書化する方法はありません。主な理由は次のとおりです。
あなたは何を知っていますか？あなたが見習いであれば、たとえば、stackoverflowが70Kで金色の
Javaバッジを持っている人よりもはるかに詳細なドキュメントが必要になります。会社で始めた人が何を知っているか、ドキュメントで何を説明する必要があるかを事前に知るにはどうすればよいですか？ドキュメントとコードの同期をどのように保ちますか？コードはさまざまな方法で検証されます：単体テスト、コードレビュー、本番環境での実行。ドキュメンテーションが間違っている場合、誰かがそれを読んで注意する必要があります。つまり、ドキュメントはコードよりもはるかに早くエージングし、人々はすぐに不信感を抱き、それを無視するようになり、エージングがさらに速くなります。
いつ文書化しますか？早いですか？これにより、ドキュメントが存在する可能性が高くなります（前のポイントを参照）。遅い？それが行われない可能性を上げます-これまで。
何を文書化しますか？ 10,000フィートの鳥瞰図？最も有用であり、時間の経過とともに有用性を維持する可能性が最も高いですが、ほとんどの場合役に立たない-バグをハントするときを言います。
なぜ文書化するのですか？経営陣を幸せにするためだけに？彼らは何を知っていますか？または、コードが非常に悪いために文書化する必要がありますか？代わりに読みやすいコードを書くのはどうですか？
私は意図的なプログラミングでいくつかの希望を持っていましたが、それはまだうまくいきませんでした。
私の現在のアプローチは、25年以上の経験に基づいており、最初に読み取り可能なコードを記述し、ドキュメントテストをユニットテストに組み込むことです。
- ユニットテストは嘘をつかない
- シンプルである必要があります（4〜10行のコード）
- 彼らはコードの各機能を次々に説明します
- すぐに実行できます（当社のルールでは、すべての単体テストは10秒未満で実行する必要があります）
私たちの会社から始めた人は、2〜3回のマウスクリックでデバッガーを実行し、コードがどのように機能するかを確認できます。
最大の利点：とにかく単体テストを記述する必要があります。文書化の目的でもそれらを使用しないのはなぜですか？
一言で言えば-プロセス。私は航空宇宙業界で働いています。ソフトウェア開発サイクルの一部として特定のアーティファクトを生成する必要があるプロセスがあります。 QA内のさらに別のプロセスにより、これらのアーティファクトが確実に生成されます。レビュープロセスは、生成されたアーティファクトが必要な詳細レベルと精度のレベルを満たしていることを確認します。さらに別のプロセスは、他のプロセスの成功などを実現します。
それは完璧には程遠く、安くはなく、何かを成し遂げるのに多くの努力を必要とします。開発者は、コードのすべての行を読んで理解しなくても、数百万行のコードベースを維持することができます。これを達成する他の方法は知りません。 「コードは福音である」コーダーは、これらの生命に関わるリアルタイムの複雑なシステムに直面すると、惨めに失敗します。ドキュメンテーションは、コードが何をするかを100％正確に反映したものではありませんが、コードよりもコードが何をすべきかを詳しく説明しています。したがって、コードがドキュメントに書かれているとおりに実行されない場合、コードはおそらく間違っています。
技術ライターは使用しません。ただし、私たちはすべきだと思います-プログラマーは英語の優れたライターであるとは限りません。テックライターを活用して不器用な技術を簡潔な英語に変えることは、大きな利益のための小さな投資です。
ドキュメンテーションは好きではありません。それは嘘をつくことができ、コードはできません。必ず、アプリケーションの上位レベルの概念に関するドキュメントがありますが、コードのドキュメントはありますか？これは、コードが明確でないという大きな兆候です。
しかし、私は疑似英語である高水準言語（主にC＃）でコードを作成しています。
私が純粋に内部のドキュメントにテクニカルライターを使用している人は誰も知りません。問題、特に下位レベルのドキュメントの場合、書かれたドキュメントがコードの実際の動作と同期しているため、書かれたドキュメントは、最小限の変更、つまり、ソフトウェアの機能の高レベルの概念とその理由を変更しますか？どのような仮定が行われ、どのような代替設計が破棄されたか。テストは、低レベルのものを文書化するために使用でき、それらを実行すると、コードと同期しているかどうかがわかります。
関数/メソッドまたはクラスがどのように機能するかを低レベルで理解するには、ユニットテストを実行すると、現在のコードベースと同期しているかどうかがわかります。コメントやテキストベースのドキュメントで確認できるものではありません。とにかく、自動化された単体テストは、多くの理由でほとんど必須です。
統合およびシステムテストは、他のものを文書化するのに役立ちます。システムはどのように使用されると想定されていますか？オペレーターが使用するワークフローは何ですか？自動統合とシステムテストは便利ですが、少なくともスクリプトによる手動テストが必要です。また、すべてのケースをテストすることができない場合や、別の方法で意図を取得する必要がある場合は、このレベルに関する追加の説明が必要になる場合もあります。
テストは文書化があまり得意ではないことがあります。アーキテクチャが頭に浮かびます。アーキテクチャはUMLで合理的に文書化できますが、低プロセスショップでは5分のホワイトボードと経験豊富な開発者で十分でしょう。
IBM、Microsoft、Googleなどの大企業の開発者は、コードの規則に従い、適切に記述されたコードを確保し、コードレビューを実施して、不十分に記述されたコードを発見します。文書化が不十分なコードは、不十分に記述されたコードと見なされます。
ソフトウェアの技術ドキュメントの主なソースはソースコードで、その他のドキュメントは副次的です。テクニカルライターは通常、技術（および場合によってはマーケティング）情報をユーザー（パンフレット、マニュアル、チュートリアル）に伝えるために採用されます。開発者は、よく書かれたソースコード（およびAPIドキュメント）に満足する必要があります。
熟練したプログラマーは、コーディング中とコーディング後ではなく、自分のコードを文書化する習慣を習得しているはずです（科学者が実験後と実験を記録するのと同じ方法で）。コードのドキュメントは、正しく、明確で、シンプルでなければなりません。コード自体は、説明の長い段落の必要性を減らすために自己説明的である必要があります。
Java（javadoc）、PHP（phpdoc）、Python（pydoc）などの一般的なプログラミング言語のソースファイルからAPIドキュメントを生成するために使用できるツールがあります。 、およびRuby（rdoc）。また、ドキュメントの不足など、一般的なコーディングの間違いがないかコードを分析するために使用できるツール。