上司に（丁寧に）彼のコードにコメントするように依頼するにはどうすればよいですか？

私は上司に教えられています（学校を卒業したばかりで、彼は少しプログラミング経験のある人が欲しかったので、彼はその会社が専門とするものについて私に訓練することを選択しました）、ASP.NET MVCアプリケーション、いくつかのHTMLとCSSでの作業を開始しました。彼が私に提供してくれたWebデザインには問題ありません（明確にすることなく理解するのは非常に簡単です）。

しかし、たとえば、彼は私にASP.NET MVCに関連するタスクを提供してくれました。しかし、彼は私に与えたコードでは何も説明しません。（私たちはVisual Studio 2013でソース管理を使用しています）、文字通り何百行ものコードであり、何をすべきかについての背景はありません。私が見ている種類のコードは、今まで見たことのないコードなので、試してみて理解するのは本当に難しいです。

私は彼にさらに質問をしようとしますが、彼は常に仕事をしています（彼自身の仕事です）。

それで、物事を把握するまで私を助けてくれる何か、上司に彼に与えられたコードにコメントを入れるように頼むにはどうすればいいですか？

あなたは「深い終わり」にあり、私の意見では、それが学ぶための最良の方法です。あなたが手がかりがないものを見ているからではなく、それはあなたがより機知に富み、どのコンポーネントがあなたが新しいシステムでどの役割を果たしているかを知ることを強いるからです。

上司が忙しすぎて、好奇心is盛な人を扱うことができないのは助けにはなりません（そして、あなたは完全にあなたの好奇心をそそる権利の範囲内にいます。しかし、残念なことに、あなたの学習のために先輩にスタイルとアプローチを変えるように頼むことは、特にあなたが忙しいと言っている人に対処しているので、あまりうまく行かないかもしれません。

慣れていない数千行のコードの前に座っているのが普通です。コメントを付けて白黒で説明できるとは限りません。ただし、初めて使用するときに学習するために、間違いなく彼にコメントを求める必要があると感じた場合は、おそらくその理由を説明してください。彼はしばしば忙しいので、質問で彼を悩ませたくないという事実のためです。あなたが彼に何かをするように言っているようにこれがはるかに少なくなるだけでなく、それは彼がどのように代わりに質問する時間を脇に置くことを好むかについての議論の床を開きます。

まず、何千行ものなじみのないコードをクロールし、失われたと感じるのは、すべてのソフトウェアプロジェクトがどこからでも最初からどのように存在するかです。

あなたと経験豊富なプログラマの最大の違いは、あなたがそれに慣れていないことです。

留意すべきいくつかのポイント：

1. 十分な努力をすれば、すべてのコードを理解できます。数分以内に何かを理解できないと、多くの人がフラストレーションを感じます。それよりも忍耐強くなってください。

2. 優秀な上司は、中断や質問に対して可能な限りオープンです。優秀な従業員は、中断や質問を最小限に抑えるために、できる限り努力します。それを意識してください。

3. 中断は質問よりも費用がかかります。ディスカッションを統合し、混乱した感じの会話を終わらせないことで、時間と上司の時間をより有効に活用できます。

4. あなたの上司はあなたよりも優れたプログラマーです。（おそらく。）それはあなたがいくつかの分野で強くなることができないということではありませんが、全体的に彼の専門知識は優れています。多くの経験を積むまで、できる限り彼の専門知識から学んでいることを確認してください。

5. より多くのコメントがコードに非常に役立つと確信している場合は、上司に尋ねてください。「ある場所で何が起こっているのかを理解するのは難しいです。物事を理解するとき、コメントを追加しても構いませんか？」たぶん彼はコメントが嫌いだ。たぶん彼はそれを好きになるでしょう。たぶん彼は無関心でしょう。

しかし、最終的には、今から2か月後、これを聞いて「問題があるのか​​しら？これはそんなに悪くない。ええと、関係ない」と思うかもしれません。

上司がすべての質問に答える時間がない場合、なぜ彼は彼のレガシーコードにコメントする時間があると思いますか？さらに、彼のコメントが、あなたが今理解していない部分を本当に説明していると思うのはなぜですか？私の経験では、上司に頼むだけで上司のプログラミングスタイルを変えようとしてもうまくいかないでしょう。

あなたはこのような状況でできる最善のこと：あなたがあなたの仕事をするために理解する必要があるコードの部分はコメント自分でします -もちろん、これらの部分を理解したら、そして上司からこれが大丈夫だというコミットメントを得た後。あなたまたは上司がコメントを追加して何かを壊す恐れがある場合は、別のブランチに追加し、トランクにマージされる前にコメントを確認する時間を取るかどうかを上司に尋ねてください。上司には限られた時間の予算しかないので、合理的な時間を費やして、特定の部分が自分で最初に何をするかを把握してください。本当に行き詰まったら、質問をリストに書き留めて、たとえば30分間邪魔する代わりに1日に1回上司に聞いてください。私の経験では、このアプローチは、彼らがあなたを助けてくれる限り、彼らが非常に忙しい場合でも、ほとんどの人でうまくいきます-あなたの状況では確かにそうです。

これにより、必要なコメントを確実に取得でき、上司は追加情報が必要な場所を確認できます。そして、自明でないことだけをコメントするように自分を制限している限り、あなたのコメントがコードベースの全体的な品質を向上させる可能性が高く、それはあなただけでなく他のすべての人にも利益をもたらすかもしれません上司を含むコードを処理する必要があります。

まず、コードを適切にコメントするための例を挙げましょう。

それから、私はいつもこれをしなければなりません。ローカルコピーをチェックアウトし、それを確認して自分でコメントします。（チェックインする場合は、それらをすべて削除することができます-誰も気にしない場合はそのままにしておきます）。これ（私がコメントしたもの）、私は正しいですか？あなたは実際のコメントを行ったかもしれませんが、それは終わっており、それがポイントです。

これは単なる個人的な要求ではありません。あなたは習慣/文化を変えようとしていますが、それは簡単ではありません。廊下での会話や電子メールで達成できるものではありません。それはあなたの側でいくらかの努力をするつもりです。

あなたが世界で見たいと思う変化でありなさい。

引用はマハトマガンジーに誤って起因している可能性がありますが、それは適切なアドバイスです。コードベースをパズルで解こうとするとき、上司に確認された後、見たいコメントを可能な限り書き、コミットします。利点：

• しつこくするのではなく、積極的に取り組んでいます。
• あなたは良い例を設定しています。最良の場合、上司/チームは利益を確認し、それに追従します。
• コメントのいくつかは、おそらく言うだろう/* Mystery parameter 3 */か、/* 2015-02-09 AidanQuinn: Is this code ever called? */それらが適切に文書コードのいずれかにあなたの同僚のための機会であるか、潜在的なバグを修正します- 。
• コミット前のレビュー中に、あなたが書いたコメントが不正確であることが判明した場合、同僚はコードが不明瞭であることを知っています。

これを行う際の書き換えやリファクタリングは控えてください。コメントの導入はほとんどリスクがないはずです。何かを書き換える場合は、それらの変更を個別のコミットとして保持してください。

（ただし、このプロジェクトに着手する前に、コメントへの期待が合理的であることを確認してください。コメントの良いコードのアイデアが標準外である場合（例1、例2）、ご自身。）

追加のコメントは求めませんが、次のようなアイデアがあります。

1. 上司との座り込みをスケジュールし、高レベルでコードを調べてもらいます。これで開始できます。数時間から半日くらいかかると思います。これには、全体的なデザイン、使用されるパターンなどが含まれます。
2. テストプロジェクトを作成し、コードに対する単体テストの作成を開始します。これにより、コードに影響を与えることなく理解できます。バグも見つかるかもしれません！
3. 特定の領域を理解するために、必要に応じてコードをデバッグします。
4. バックログから機能強化またはバグを取り除いて作業します。

コメントは問題ありませんが、コードが簡単な方法で記述されている場合、数日後に理解できるはずです。

また、すべてを理解することを期待しないでください。最初に重要な領域に焦点を合わせてから、必要に応じてコードベースの知識を広げることをお勧めします。

私はおおよそ1年前にあなたと非常によく似た状況にありました。私はプログラミングの経験がほとんどない状態で作業を開始しました（最初はオブジェクト指向や他の言語を少し知っていました）。彼はいつも助けてくれましたが、私が持っていたすべての質問に聞きたくないと感じました。

他の人は、ここで非常に役立つものをすでに提案しています（たとえば、ユニットテストを書くが、私自身の経験から、それは私にとってゼロから少し「遠すぎる」ことになるでしょう;またはコードの一部を自分でコメントするが、それは最初のポイント/質問によっては難しいので、すぐにお尋ねします）。次のポイントは私がしたことと私が助けたものを要約していますが、それはあなたの問題がどこにあるかによって大きく異なります。

また、私はあなたが本当にC＃でコメントを必要としないと言った@AK_に同意しなければなりません。これは100％正しいとは限りません（たとえば、リフレクションが多いコードなど、コメントが間違いなく役立つ領域があると感じています）が、本質的にはそうです。適切な名前のメソッドと変数を使用して本当に「クリーンなコード」を記述し、多くの小さな「バイト」のコードがある場合、それらはほとんどまったく不要になります。これまでのコードを読むときにコメントの必要性を感じるたびに、それが何であるかを理解した後、私はそれが行われた方法に非常に不満であり、最初は良いリファクタリングによってより明確になったかもしれないと思った。 編集：ここでは、ドキュメントではなくC＃コメントについて説明しています（ドキュメントまたはXMLコメントとは別です）。ドキュメントは常に重要だと思います。

• 問題が何であるかを正確に特定し、分類できるかどうか。つまり、言語自体にまだ問題があるか、特定の構文（たとえば、ラムダ式とLINQ全般、またはReflection）を理解していないのですか？コードの行を理解していないと、メソッド/ブロック全体が何をするのか理解できないため、自分でコメントするのは難しいでしょう。むしろ、良い本（私にとっては「C＃in a Nutshell」ですが、「C＃in Depth」も素晴らしいと聞きました）を入手して、あなたが出会ったものを読んでください。これらの問題を事前に分類すると、一度に「大きなギャップ」を埋めたり、上司に質問したりすることができるので、これが簡単になります。巨大な「ブースト」を得ることができます

• 上記と並行して、「クリーンコーディング」とベストプラクティス（言語固有ではない）に慣れるようにしました。この効果はすぐには得られないかもしれませんが、既存のものを拡張する必要がある場合、または誰かがすべてが含まれているものの代わりになぜ多くの小さなメソッドを作成したのか疑問に思う場合、遅かれ早かれ報われます;-)

• 一般的な設計パターンを把握します。彼らはあなたが読んでいるコードのあちこちに現れているかもしれません、そしてあなたがそれらを認識するならば、それはあなたにa-haの瞬間をすぐに与えるでしょう。そこにあるコードが何をしているのかを理解していても、なぜこのようになっているのか不思議に思うかもしれません。

私はあなたの「スキル」について仮定しているので、上記のテキストを受け取らないでください。私はしばしば、私の経験について話すことと「あなた」に話すことを誤って切り替えます。それは主に私が出会ったこと、そして私がやったことを意味しています。他の人が言ったように、これは非常に良い経験になる可能性があり、あなた自身のものではなく、事前にあまり知らないコードを読むことは仕事の標準です。しかし、最終的にそこで何が起こっているのかを最終的に把握し、この特定の「スキル」で良くなっていることを認識することは本当に満足のいくものです。これを機会に、本当に短い時間でたくさんのことを学びましょう、幸運を！:)

あなたはおそらく彼に彼のスタイルを変えさせるつもりはないでしょう。

できることはたくさんの質問をして、答えを書き留めることです。

私は前回の仕事で巨大なコードベースを継承し、ドキュメントはほとんどなく、コメントもほとんどありませんでした。だから私は同じ問題に30分間挑戦し、それでもそれが分からないなら、私はそれを書いたか、それを使う方法を知っている誰かに尋ねに行くだろう。その後、彼が私に言ったすべてのことを文書化します。ほとんどはドキュメントに記載されており、一部はコメントとしてコードに記載されています。1年後、私はドキュメントの大部分を実際に書き、コードベースについて多くのことを知りました。

幸運を！

私は同じ問題を抱えていました。物理学者のIm学生であり、プログラミングの経験が豊富です。私は多くの言語でプログラミングをしていましたが、プレミアムアプリケーションには何もしていませんでした。

私はウェブ開発者の仕事に応募しましたが、彼らは即座にウェブプログラミングのバックエンドに私を置きました。ボスがノードRESTアプリケーションのベースAPIを見せてくれたとき、私は捨てようと考えていました。私はコールバックととても奇妙な構文を持つ関数を見たことがない。そして、私は上司に、コードに何も見当たらなければ問題があるかどうか尋ねます。彼は悲しいです、彼は私がそれを理解するために1ヶ月持っていることを悲しい、そしてその間に私は別のフロントレンダーで私をテストするためのCMSを作ります。

さて、私はその時に1行のコードを実行し、私が知らないことすべてをグーグルで調べました。したがって、1週間が経過し、コードに十分に精通していたので、フロントエンダーとの共同作業を行うことができました。初めの私のコードはがらくたでしたが、それから3か月後に私を見つけました！私たちのソフトウェアアーキテクトよりも優れた高速コーディングをしています！

Learninigを停止することはないだろうと思います！私のモト->学習を続け、落ち着いてください:)ボスに依存せずに、独立して、直接彼に尋ねてください。しかし、最も難しい問題だけです。自分の研究者がそれを理解した後、あなたは幸せになるからです。そして、あなたが何か間違ったことを学ぶのをやめたとき、良いプログラマーになるための方法を学んでください。

あなたが上司から学ぶなら、あなたは彼があなた自身の標準を設定するより良くなることはありません、あなたのIDE、Linux wmiiのためのブラインドタイピング、VIMまたはVIMプラグインを学ぶので、あなたはいつか上司を超えて、彼より良くなります！

主に安全関連のもの（SF-PD）に取り組んでいる20年のソフトウェアエンジニアとして、私はあなたの上司があなたがあなたの模範になりたい人ではないかもしれないと言わなければなりません。コメントの欠如は、仕事を適切に行う方法を学んだことのない独学のアマチュアコーダー、または経験の浅いエンジニアの兆候です。あるいは、単に時間がないエンジニア-締め切りと便宜はあなたのコードに恐ろしいことをすることができます！;）しかし、それは間違いなくすべての有能なソフトウェアエンジニアにとってアンチパターンです。

あなたの上司は非常に優秀なコーダーかもしれませんが、彼は優秀なソフトウェアエンジニアではないようです。エンジニアは集合的なグループエクスペリエンスを使用して、他の人が既に見つけた落とし穴を回避します。応力解析が機械工学の集団グループエクスペリエンスの一部であるのと同じように、効果的なコメントはソフトウェアの集団グループエクスペリエンスの一部です。しかし、効果的なコメントとしてカウントされるものはより流動的であり、間違いなく経験から得られるものです。

最も基本的なことは、コメントはコード行が何をするかを言ってはならないということです。関数が何をするのかというコメントも不要な場合があります（特にC＃では）。ドロスの中に重要なものが見つからないので、過剰なコメントは同じくらい効果的ではありません（そして経験不足へのポインタ）。初心者として、あなたはまだコードの「何」を理解することに取り組んでいるかもしれません。そのためには、彼が何をしたかを読んで理解する必要があります。

コメントするために重要なことは、しかし、彼らが言うことですWHYコードの行または関数は、それが何を行い、これは明らかではないかもしれないところ。モジュールYの前にモジュールXをセットアップする必要がありますか？ファイルが既に開いているかどうかを確認するためにリターンコードをチェックすることは重要ですか、それとも別の場所でチェックされているために意識的にリターンコードを無視しますか？コードの「理由」は、経験に関係なくすべての人に関係します-そして、何か特定の方法を行う正当な理由を忘れた6か月後にも彼に関係します。コメントは他の人だけのものではなく、将来あなたを助けるためのものでもあります。

上司に迷惑をかけたくない場合は、スマートな質問をしてください。「なぜ」について尋ねることに焦点を合わせ、「何」を自分で解決しようとします（それが本当にあいまいでない限り）。良い上司は、R-ing TFMで見つけることができなかった種類の質問ではないかと尋ねられます。また、優れたエンジニアは、他のエンジニアの生活を大幅に楽にし、わずかなコストで何かをするように求められることを気にしません。（コードベース全体にコメントを埋めるように頼まないでください！;）

同様の状況にあった、私は言うだろう

1. 上司は、理由のわからない汚い方法を（あなたが知らないコードを歩くことによって）学んでほしいと思うかもしれません。これは、他の回答で述べたように、大学での1年よりも職場での1か月のほうが多く学習する方法です。

2. これは、他の回答で言及されている「標準」です。コードのすべての行をすぐに理解しようとするよりも、どこから始めて、どのようにアプローチし、何に焦点を当てるかについて心配する必要があります。適切なツールとコードのデバッグ/ステップ実行方法について上司に尋ねてください。この種の質問はあなたにいくつかのポイントを買います。

3. 定期的に、上司にあなたのやり方についてのフィードバックを求め続けてください。そうすれば、上司が同じ状況にいる多くの人々を見て、彼らがどのように行動したかを把握していると仮定して、百分位数で考えることができます。

4. これを機会に利用し、コードの理解が深まるにつれて、元々上司に尋ねることを期待していたコメントを追加し続けてください。

あなたが本当に彼にコードにコメントを入れるように依頼したい場合（私はお勧めしません）、実際にいくつかのコメント（ほとんどは自明です）を使用できる編集する必要があるコードを見つけて、質問することをお勧めしますこのように「私はここでこのコードを見ていましたが、[あなたが持っている問題]を理解しようとしていますが、説明に役立つコメントが見つかりませんでした」。基本的には、あなたがそれを理解することに努力していることを示し、なぜあなたとあなたの両方がそこにあるコメントから利益を得ることができるのかを説明しようとします。

おそらく、よく書かれたコードの90％はコメントを必要としません。最適化されてかなり緊張したコードの部分のみを文書化したいだけです。私が会社で働いていたとき、変更したコードをすべて文書化する必要がありましたが、コメントは基本的にコードの可読性を損なうことになりました。貧弱なコメントに注意して関数のデバッグに1週間費やし、最終的に、そのようなフラグを「false」に設定することについて読み続けたコメントが、実際にフラグを「true」に設定したすべての問題であることがわかりました想定どおり。

コード内のコメントに何かが書かれた理由を理解させたい場合は、おそらく（あなたが新しいと考えて）ビジネスのニーズをまだ理解していない可能性があります。あなたはすべての構文を知っていて、コードを読むことができると確信していますが、コードの目的を知らなければ、少し迷ってしまいます。

思い浮かぶのはペアプログラミングです。あなたはあなたの上司があなたの進歩に感銘を受けたと言うので、彼と一緒に働くことを提案できます。これは、長期的にあなたとあなたの両方を助けます。あなたの上司は、当たり前のことを説明する必要があることに気付くでしょう。そして、あなたはビジネスについてもっと学ぶでしょう。

他の人が言及したように、これは非常に一般的ですが、それはあなたがそれを吸い上げてすり抜けなければならないということではありません。思っているほど深くコードを理解する必要はありません。また、「ディープエンド」をより浅くするための具体的な戦略があります。

• 手元のタスクに関連するコードで何かを見つけます。通常、最も簡単に検索できるのは、GUI上のボタンのラベルなど、ユーザーに見えるものです。見つけた場所を書き留めてください。これがアンカーポイントになります。
• ここで、コードを1歩先に検索して書き留めます。誰がボタンを作成しますか？ボタンがクリックされると、どのコードが呼び出されますか？
• ソース管理は、多くの場合、一歩先のコードを見つけるのに役立ちます。表示しているコードがいつ追加または変更されたかを確認し、同時に他にチェックインされたものとその理由を確認します。
• 変更を加えるのに十分なことがわかるまで繰り返し、さらに何も欠けていないことを確認するために1レベル深くします。
• いずれかの時点で動けなくなった場合、非常に具体的な質問があります。たとえば、「このボタンがどこからインスタンス化されるのかわかりません。」

この件に関する私の0.02ドルを以下に示します。私は排他的な答えを提案しているわけではありません。ここで述べられたことの多くは非常に重要です。

上司が自分のコードの一部をコメントする方が、そうでないよりも簡単に/時間をかけずに見つけられるように、ソーシャルエンジニアリングを少し試してみます。

さて、あなたが大きなリスクを冒して彼を困らせるなら、これは非常に簡単です-しかし、私たちはそれをしたくありません。（サイドノート：あなたは彼があなたにコメントを書き留めたり口述したりせずに何もすることができないかもしれません。

では、代替手段は何ですか？状況に応じたいくつかのアイデア。

オプション1

1. Xを実行しているコードの一部を理解するために時間をかけてください。
2. 次に、Yを誤解する合理的な方法を考えます。
3. あなたが現在それを理解しようとしていることを上司に（メールで、または朝食で何とか言って）伝えてください。
4. コードの意味が明確ではないというコメントを追加しますが、Yと理解します。このコメントを彼に見えるようにしてください-しかし、一生懸命しようとしないでください！
5. Yを仮定して行動し、上司があなたの行動に気付くようにします（そうすることで、誤った仮定で長時間仕事を無駄にすることはありません）。
6. 上司が率先してあなたを正すべきです。この時点で、「このコードに間違った仮定を立てないようにするために、このコードにコメントがあればいいのにと思っています。自分で追加したコメントを修正します。一般的な説明を手伝ってもらえますか？あれこれのコードの断片ですか？私は正確な意図を理解するのに十分な経験がありません、そして、私はほんの数文がトリックをするでしょう。」か何か..

オプション2

トレーニング中です。彼との（追加の？）固定周波数の毎週の会議を手配してみてください。この会議ではいくつかのコードを検討しますが、彼がすべての行を説明する必要がないように十分に準備する必要があります。ある時点で-うまくいけば-コメントを追加しただけで会議をスキップできることに気付くでしょう。

オプション3

別の同僚に、あなたと同じコードを理解できないようにしてもらいます。二人とも、同じ質問をする異なる時間にボスに近づきます。それは彼が彼が何かをしていないことに気付かせるための確実な方法です...しかし誰もが同じプロジェクトで役に立つ同僚の贅沢を持っているわけではありません。

それで、物事を把握するまで私を助けてくれる何か、上司に彼に与えられたコードにコメントを入れるように頼むにはどうすればいいですか？

コードを理解できない場合、コメントがあなたの解決策だと思うのはなぜですか？

彼のプログラミングスタイルはわかりませんが、関数と変数の名前が誤解を招く場合、コードの理解が非常に難しくなります。ただし、名前や機能、さらにはプログラムの構成（クラス、メソッド、プロパティなど）がコードを理解しやすくする場合、コードは実際に自分で話します。

彼にプログラムのアーキテクチャを尋ねて、何かを要求したい場合は、関数のより意味のある名前を要求してください。それは彼にとってより便利です。

これを丁寧に尋ねる方法があったとしても、上司が自分のコード内のコメントについてどう考えるかについて、2つの可能性があります。

1. 彼のコード内のコメントがあれば良いのか、

2. 彼のコードにあるコメントは、良いものではありません。

上司が自分のコードにコメントを入れるのは良いことではないと考えている場合（そして、これには非常に良い議論があります。つまり、コードはドキュメントであると想定され、ドキュメントは何かを正確かつ明確に規定しません）実際にそれを行うコードとして）、何も起こりません。

今、上司が自分のコードにコメントを入れるのは良いことだと考えている場合、上司が自分のコードを調べて、それがどのように機能するかを理解し、コメントを追加するよう指示する可能性がかなりあります自分でコーディングします。（これについても非常に良い議論があります。すなわち、あなたは学ぶ必要があり、彼の時間は定義上あなたの時間よりもはるかに貴重です。）

そのため、これを行う必要がある場合を除いて、何も言わない方が良いでしょう。