コードは自己文書化されていると思いますか？[閉まっている]

これは何年も前に就職の面接で卒業生として出された質問であり、私の頭を悩ましているものであり、満足のいく良い答えを見つけることができませんでした。

問題のインタビュアーは白黒の答えを探していましたが、中間的なものはありませんでした。質問の背後にある理論的根拠について尋ねる機会はありませんでしたが、なぜその質問が開発者に投げかけられ、あなたがイエスまたはノーの答えから何を学ぶのか興味がありますか？

私自身の観点からは、Java、Python、Delphiなどを読むことができますが、マネージャーが私に近づいて、プロジェクトの進行状況を尋ねると、「コードは80％完成しています」と言いますあなたは私を撃shootingし始めます、私はこれが開発者によっていくつかのオフィスで発言されたことを聞きました）、その自己文書化はどのくらい正確ですか？この質問が奇妙に思われる場合はおologiesび申し上げますが、インタビューで誰かに質問される理由をよりよく理解するために、質問して意見を聞きたいと思います。

部分的に。

Big English Wordsを使用するコードは、すべての関数と変数の名前が何をしているかを教えてくれるという点で、部分的に自己文書化できます。しかし、おそらく理由はわかりません。

比較する：

a->b;
# what is b doing? what is the a object?

carEngine->startIgnition;
# much more clear what objects are involved

しかし、あなたはまだ車が始動されている理由を知りません。したがって、部分的にのみ。インタビュアーが白黒の答えを期待しているのは、ひどいことです。ただし、彼の白黒の見方に非常に強いものが含まれている場合を除きます。

いいえ。コード自体は自己文書化されていません。

その理由は、コードがHOWを示し、コードを維持するために人間が知る必要のあるWHYを気にしないからです。

したがって、すべての理由を説明する追加のコメントが必要です。変数名に決定の一部を含めることで制限できますが、回避することはできません。

適切なコードは「方法」を示します。適切なコメントはあなたに " なぜ "を伝えます。

したがって、コードは物事の達成方法を自己文書化する場合がありますが、その理由を文書化することはできません。

彼らが中間的な根拠を許さずに白黒の答えを主張するなら、答えはノーです。

より完全な答えは、そのコードが合理的だ最大限に自己文書化する必要がありますです、しかし、コード内のドキュメントのいくつかのタイプを含めるための合理的な方法はありません。たとえば、フォームAで収集された情報、フォームBで収集された情報、フォームCで収集された情報を文書化するだけでコードはうまくいくかもしれません。この方法でデータを増やすと、（たとえば）3つではなく2つのフォームのみを使用した場合と比較して、エラーがx％減少しました。

最も些細なコード以外の部分は、少なくとも一部の外部ドキュメントの恩恵を受けることができます。

私の答え。可能な限り、コードを可能な限り自己文書化するよう努力する必要があります。これには多くの理由があります。最初に記述されたとき、10に1行の平均には誤りがあります。コードの間違いを見つけて修正する傾向があります。ドキュメントの間違いは残される傾向があります。メンテナンスでは、コードとドキュメントがバラバラになるのが一般的です。

ただし、コードを明確にすることでできることには制限があります。これらの場合、文書化する必要があります。

文書化について選択できる場合はどうですか？私の見解では、メンテナンスは組織に強く依存します。優れたソフトウェア開発者と厳格なコードレビュープロセス（たとえば、Googleのような）があれば、プロセスや人々は、コメントが維持されないことを心配する必要がないようにすることができます。その場合、コメントが多いスタイルが非常に理にかなっています。（実際、Googleはコメント重視のスタイルを持っています。）しかし、より典型的な組織がある場合は、私が見たコメントを非常に不信に思うでしょう。コードを自己文書化しようとしています。そのような状況では、コメントは不要だと思います。

コメントのメリットとデメリットに関する興味深い会話については、私が参加していた古い会話についてhttp://www.perlmonks.org/index.pl?node_id=65153を参照してください。（その会話と同時に、友好的なプライベートチャットセットがありました。会話のネガティブな半分だけが公開されていることを常に後悔していました。） 、しかし、私はまだ会話に価値があると思っています。

私はこの質問が頻繁に出てくることを発見し、しばしばそれについて宗教的な熱意を抱いています。ここに私の見解があります...

理想的な世界では、次のことを述べることができます。

コードは、コメントを必要とせずにロジックを追跡できるように作成する必要があります。

OK、これで十分ですが、問題は理想的な世界に住んでいないということです。この理想的な声明を達成するにはいくつかの問題があります。

1. 多くの場合、プログラマは、プログラミングの対象となる業界の専門家ではありません。startEngine(Car car)（ほとんど）誰もがここで尋ねられていることを理解できるなどの機能を理解するのは十分簡単です。しかし、現実の世界に移ると、物事は少し曖昧になります。たとえば、getSess(String tid, String aid)DWDMシステムを理解しているトランスポートエンジニアはこの機能を完全に理解できますが、プロジェクトに参加したばかりの新しいプログラマーにとっては課題となります。適切に配置されたコメントは、コードをタイムリーに理解するための移行を容易にするのに役立ちます。

2. コードの保守を依頼されたプログラマーは、多くの場合、コードの元の設計者ほど熟練していません。元のプログラマは、特定のタスクを達成するための高速で簡潔で効率的なアルゴリズムを作成するのに十分なスキルを備えていた可能性があります。しかし、そのコードを維持することを任されたプログラマーは、何が起こっているのか理解しようとするのに苦労するかもしれません。適切に配置されたコメントは、コードをタイムリーに理解するための移行を容易にするのに役立ちます。

3. 何回コードを書いたことがありますか。後でそれをやった理由や達成しようとしていたことを理解するのに苦労しましたか？私たちは皆、時々それをします。多くの場合、問題を解決し、問題のわかりやすい解決策を作成することは2つの異なる考え方です。あなたがゲートから完全にコードを書くことができる人でない限り、あなたはしばしばあなたのコードに多くの失敗をします。また、しばらくこのコードに戻ることができない場合もあります。 適切に配置されたコメントは、コードをタイムリーに理解するための移行を容易にするのに役立ちます。

4. ユニークな状況には説明が必要です。たとえば、プログラマーは、DWDMデバイスと通信するコードの一部に100msの休止が入れられたのかと疑問に思うかもしれません。デバイスの取り込みが遅いため、一時停止が必要であることを次のプログラマーに知らせてください。コマンドを見逃す可能性があるため、貴重な情報です。 適切に配置されたコメントは、コードをタイムリーに理解するための移行を容易にするのに役立ちます。

うまく書かれた「自己文書化」コードは見つけるのが楽しいです。適切に配置された有益なコメントを備えた、うまく書かれた「自己文書化」コードは、天の恵みであり、非常にまれな発見です。

最初の質問の両側に引数を与えるだけです：

はい、コードは自己文書化されています。変数、メソッド、およびクラス名はすべて読みやすく、理解しやすいように作成できるため、これは自己文書化の形式です。コードスタイル内には、標準の手順と見なされるXMLドキュメントを最後に提供するものがあります。言い換えれば、開発者の仕事の一部は、コードと混在する可能性のあるドキュメントを提供することです。

いいえ、コードは自己文書化されていません。行われたビジネス上の決定、行われた設計上の選択、およびその他の要因は、コードの行には表示されないため、コードベースの外側に書き留める必要があります。したがって、外部ドキュメントが必要であり、これらはその例です。

質問のポイント：回答の制限を認識して部分的な回答をしますか、それとも良い方だと思う側に盲目的に頼りますか？答えがイエスかノーの場合、どれだけの確信があなたの答えにありますか？それは、「なに...？」信じられないほどの知性！」かなり慢で威厳のある答えとして、そのトーンで答えを出してくれる人を想像できます。

明らかに彼はクヌースのスタイルの文芸的プログラマーでした。LP弟子にとって、コードは有効であるために自己文書化されていなければなりません。したがって、唯一可能な答えは「はい」です。

ここでの問題は、読み書きのできるプログラミング言語が多くないこと、そして私が広く商業的に使用していることを知っているものがないことです。だから、どこかニッチなポジションにならなければならないでしょう。

インタビュアーが探していたのは、「どのように自己文書化コードを書くのですか？」暗黙の「ドキュメンテーションに対するあなたの態度は？」

ロバート・C・マーティンという名前の男による非常に感動的な講義に行ったことがあります。

彼は明らかに純粋主義者の立場を少し示していましたが、コードを小さな再利用可能なメソッドに分割し、次のような簡単なトリックを使用するとき、彼のアドバイスを取り入れました：

• メソッド内のすべてのステートメントを同じ抽象レベルに保つ
• 制御フロー条件またはループブロックの内容をメソッド呼び出しに引き出す
• クラス内のいくつかのメソッドに同じパラメーターを渡し、新しいクラスを分離する場合
• そして、不可解なブール式をメソッド呼び出しに置き換えるなどの簡単なトリック
• 等...

理解しやすく保守しやすい、読みやすい、多少自己文書化されたコード（簡潔でありながらわかりやすい名前を付ける限り）になります。

私はそのようなものが本当に役立つことを発見しましたが、それをうまく行うには設計パターンの知識が必要であり、クラスと高レベルのメソッドのドキュメントでアプローチを確実に補完する必要があります。

通常、自己文書化コードは、コードの目的が自明であるように、変数、関数などに命名規則を使用することを指します。したがって、コード自体は自己文書化されません。3番目の段落で何を言っているのかわかりません。それは自己文書化コードとは何の関係もないようです。

ジャックリーブスはコードがデザインであるという説得力のある議論をした。多くの関係者に関する限り、実際のコードはシステムが何をするかを伝える唯一の「ドキュメント」です。稼働中のシステムは、設計されたシステムからさらに遠ざかる傾向があるため、他のすべては減衰します。コードからドキュメントを生成したとしても（今日の多くのUMLツールでできるように）、それはその時点でのシステムの正確なドキュメントにすぎません。

はい、コードは自己文書化されます。それがどれだけうまく文書化されているかは、別の質問です。

経験を積むにつれて、本当の答えはコードと読者の環境が自己文書化のレベルを決定することだということを学びました。

読者の環境と作家の環境の違いを最小限に抑えるために、コメントを追加します。より多くのコメントが必要になるほど、通常は作家の経験が少なくなります。ソフトウェア開発のこの側面を説明する非常に素晴らしいエッセイがありますが、誰が書いたのか、どこで見つけたのか覚えていません。

ほとんどの人がその質問に期待する答えは「いいえ」であることを知っていますが、「はい」と言います。就職の面接でこれを尋ねられたとしても、私はまだイエスと答えます。

私はオープンソースとクローズドソースで多くの異なるプロジェクトに取り組んできました。それらは、プログラマーのメモとして残された簡単なコメントから完全なAPIドキュメントに至るまで、ドキュメントの範囲が広い。APIのドキュメントは素晴らしいものになりますが、筆者は常に、記述言語のドキュメントではコードの実際の動作を判断するには不十分な状況に常に陥っています。最終的には、ソースコードを調べたり、アプリケーションをリバースエンジニアリングしたり、開発者にソースアクセスを促してソースコードを調べたり、さらに詳細に指定したりしました。

私にとって、コードは究極のドキュメントです。プログラムが何をしようとしているかをいくら言葉で書いても、正確な振る舞いはコードによって定義されます。

コードを書くときは、可能な限り自己記述的にコードを作成するようにしてください。ただし、他の人が述べたように、複雑なプログラムでは、コードが実行しているすべてを完全に記述することはほとんど不可能です。私はコメントに反対ではありません。実際、コメントは英語や一部の話し言葉を読まなくてもコードがそれ自体を説明できるのに、コメントがあればコードを読みやすくすることができます。

最も有用なドキュメントはほとんどコメントではないことがわかりました。私が最近取り組んでいるほとんどのプロジェクトには、すべての異なる部分、接続方法を含むウィキが含まれています。他の人が理由を理解していないために他の人が私のコードを壊さないように、私はコードを書いているときに私の心にあったことを説明しようとします。また、他の誰かがより自信を持ってコードをリファクタリングするのに役立ちます。コードのリファクタリングをためらうことがよくあります。何が壊れるかわからないし、説明もないからです。あなたがプロジェクトで働いている唯一の人であっても、1、2年で保証します。たとえ最も美しいコードでも、なぜそこにあるのかを忘れることができても、あなたは何かをした理由を忘れます。

もちろん、時間に制限がない場合。私は25年以上、他の開発者向けにコードを文書化しました。私の立場は、別の開発者が5分で理解できるように何かを説明しようとすることです。その方法を見る人全員を25分救うと、仕事をやり遂げました。

コードを文書化するには、常にクラス図を使用する必要があると思います。コードを直接見ると、完全なアーキテクチャを見ることができるとは思いません。自分でコードを書いたり、長い間作業している場合は理解できますが、コードを見て、この新しいコードを追加する場所を検索する必要があるたびに新しい需要が発生するたびに同意します。

私たちが会社で行うことは、プロジェクトのクラス図ビューを持つことです。モデリングに時間を費やすのではなく、リバースエンジニアリング後のクラス図を使用してコードを視覚化します。コードが変更された場合、マージメカニズムがあり、クラス図は常に更新されます。

素晴らしいのは、Java docに加えて、図にコメントや制約を追加できることです。プロジェクトを逆にして、モデルを作成し、最終的にUMLクラス図として表示されたモデルからビューを抽出します。この段階ではコードを作成しませんが、コードアーキテクチャから青写真を取得し、現在のアーキテクチャを作成または拡張するためにそれに取り組みます。気に入ったらボタンを押すと、既存のコードがダイアグラムにマージされます。マージを意味し、完全なコード生成ではありません。毎回完全なコードではなく、既存のコードと私の図の間の差分のみが書き込まれます。

私は長年勉強していて、修士号を取得していて、まだコードを書いていますが、Javaライターになりたくないので、もう少し頭を使いたいです。UMLビューは、モデルの開発を使用せずに、既存の手動で記述されたコードとグラフィカルにクラス図を作成するだけで、アーキテクチャについて考え、他のチームメンバーと通信し、より良いアーキテクチャを作成するために必要なものを提供します。コードレベルでアーキテクチャを作成し、それを逆にしてモデルを確認します。ビューを作成し、コードでアーキテクチャを直接改善してから、もう一度逆にして、何が行われるかなどを確認します。これは、モデル駆動型コード生成ではなく、コードとUML間のライブ同期またはマージを伴う永続的な反復です。私が気に入っているのは、コードがUMLを駆動することであり、逆ではありません。