上司に（丁寧に）コードをコメントするように依頼するにはどうすればよいですか？
私は上司に教えられています（学校を卒業したばかりで、プログラミングの経験が少しない人が欲しかったので、彼は私にその会社の専門分野についてトレーニングすることを選択しました） ASP.NET MVC =アプリケーション、一部のHTMLおよびCSS。私は彼が私に与えてくれるウェブデザインのもので大丈夫です（明確化することなく理解するのはかなり簡単です）。
しかし、たとえば、彼は私にASP.NET MVCを使用するタスクを与えました、彼はそれを本当によく説明しています。しかし、彼は彼がちょうど私に与えたコードで何も説明しません。 （ Visual Studio 201 ではソース管理を使用しているため、文字通り数百行のコードであり、想定されていることの背景がありません。私が目にしているコードの種類は、これまでに見たことのないコードであるため、試して理解するのは非常に困難です。
私は彼にもっと質問してみますが、彼は常に働いており（それは彼自身の仕事です）、私は彼がすべてに迷惑をかけるかもしれないような気がします私の手にあるこれらの質問。
だから私が物事を把握するまで私の助けになる何かだけ、上司が彼に与えたコードにコメントを入れるように頼むことができますか？
あなたは「深い終わり」にいます、そして私の意見では、それは学ぶための最良の方法です。手がかりのないものを見ているからではなく、より機知に富み、どのコンポーネントが新しいシステムでどの役割を果たしているのかを知るように強制するからです。
上司が忙しくて探究心のある人を処理するのに役立ちません（そしてあなたは完全に探究心のあるあなたの権利の範囲内です;あなたは学びたいと思っています、それは良いことです）。しかし、残念なことに、学習のためにスタイルとアプローチを変更するように先輩に頼むことは、特にあなたが忙しいと言う人に対処しているので、あまりうまくいかないかもしれません。
慣れていない何千行ものコードの前にいるのは当たり前のことです。コメント付きで白黒で説明できるとは限りません。しかし、あなたがそれに慣れていない間に学ぶために、もしあなたが間違いなく彼にコメントを求めなければならないと感じたら、多分理由を説明してください。彼は忙しいことが多いので、質問で彼を悩ませたくないという事実のためにそれを説明してください。これは、あなたに彼に何かをするように言っているように出くわすだけでなく、彼がどのようにしてよいかについての議論への床を開きます。
まず、何千行ものなじみのないコードをクロールし、迷っているのは、どのようにeveryソフトウェアプロジェクトが、最初からどこにでもあることです。
経験豊富なプログラマーとの最大の違いは、慣れていないことです。
覚えておくべきいくつかのポイント：
十分な努力を払えば、コードのすべてのビットが理解できます。多くの人は、数分以内に何かを理解できないとイライラします。それよりも辛抱強く。
良い上司は、中断や質問に対して可能な限りオープンです。優秀な従業員は、中断や質問を最小限に抑えるために、可能な限り努力します。それを意識してください。
中断は質問よりも費用がかかります。話し合いを統合し、混乱した会話を終わらせないことで、時間と上司の時間をより有効に活用できます。
あなたの上司はあなたよりも優れたプログラマーです。 （たぶん。）それはあなたがいくつかの分野で強くなることができないと言うことではありませんが、全体的に彼の専門知識はより優れています。多くの経験を積むまでは、彼の専門知識からできるだけ多くのことを学んでください。
さらに多くのコメントがコードに大きく役立つと確信している場合は、上司に尋ねてください。 「いくつかの場所で何が起こっているのか理解するのが難しい。何かを理解するとき、コメントを追加してもいいですか？」たぶん彼はコメントを嫌っています。多分彼はそれを好きになるでしょう。多分彼は無関心でしょう。
しかし、結局のところ、これから数か月後にこれを尋ねたことを思い出して、「ああ、私は何に問題があったのだろうと思いますか？これはそれほど悪いことではありません。うーん、まあ、関係ありません。」と考えるかもしれません。
上司があなたの質問のすべてに答える時間がない場合、なぜ上司がレガシーコードにコメントする時間があると思いますか？さらに、彼のコメントが、今のところあなたが理解していない小片を本当に説明していると思う理由は何ですか？私の経験では、上司のプログラミングスタイルを変更することは、丁寧であるかどうかにかかわらず、上司に機能しないことを尋ねるだけです。
そのような状況でできる最善のこと：作業を行うために理解する必要があるコードの部分にコメントを付ける自分で-もちろん、それらの部分を理解したら、そしてコミットメントを得た後これは大丈夫だというあなたの上司。あなたや上司がコメントを追加して何かを壊すのではないかと恐れている場合は、別のブランチにコメントを追加し、トランクにマージされる前にコメントを確認する時間を取るかどうか上司に尋ねてください。上司は限られた時間の予算しか持っていないので、妥当な時間を費やして、特定の部分が自分で最初に何をするかを理解してみてください。本当に行き詰まっている場合は、質問をリストに書き留めて、たとえば30分間邪魔するのではなく、1日1回上司に尋ねてください。私の経験では、このアプローチは、たとえ忙しいとしても、彼らがあなたを喜んで助けてくれる限り、ほとんどの人で機能します-あなたの状況では確かにそうです。
これにより、必要なコメントを確実に受け取ることができ、上司は追加情報が必要な場所と、問題がないかどうかを確認できます。そして、自明ではないものだけをコメントするように制限している限り、コメントがコードベースの全体的な品質を向上させる可能性が高く、それはあなただけでなく他のすべての人にも利益をもたらす可能性があります上司を含むコードを処理する必要があります。
まず、これをあなたのコードに適切にコメントするための例にしましょう、Grasshopper！
それから、私はいつもこれをしなければなりません。私は自分のローカルコピーをチェックアウトし、自分で調べてコメントします。 （もう一度チェックインする場合は、それらをすべて取り除いてもかまいません。あるいは、気にしない場合は、そのままにしておいてください。）さらに、実際にそれ以上見えない場合は、ここで誰かに尋ねることができます。これ（私がコメントしたもの）、私は正しいですか？あなたは実際のコメントをしたかもしれませんが、それは終わった、そしてそれがポイントです。
追加のコメントはお願いしませんが、ここにいくつかのアイデアがあります。
- 上司と一緒に座ってスケジュールを立て、上司にコードを試してもらってください。これで始められるはずです。数時間から多分半日くらいはあなたがスピードを出せるように期待しています。これには、全体的なデザイン、使用するパターンなどを含める必要があります。
- テストプロジェクトを作成し、コードに対する単体テストの作成を開始します。これにより、影響を与えることなくプロジェクトを理解するのに役立ちます。また、いくつかのバグを見つけることもあります！
- 特定の領域を理解するために、必要に応じてコードをデバッグします。
- エンハンスメントまたはバグをバックログから取り除いて作業します。
コメントは問題ありませんが、コードが単純な方法で書かれている場合は、数日で理解できるはずです。
また、すべてを理解することを期待しないでください。最初に主要な領域に焦点を当て、次に必要に応じてコードベースの知識を拡張することをお勧めします。
これは単なる個人的な要求以上のものです。あなたは習慣/文化を変えようとしていますが、それは簡単ではありません。それは確かに、廊下の会話や電子メールによって達成できるものではありません。それはあなたの側でいくらかの努力をするでしょう。
あなたが世界で見たい変化をしてください。
引用はマハトマガンジーに誤って起因している可能性がありますが、適切なアドバイスです。コードベースを困惑させようとするときに、見たいコメントを書き、可能な限りコメントを書き込んでください。上司にレビューされています。利点：
- あなたはしつこいというよりは、積極的です。
- あなたは良い例を設定しています。最良のケースでは、上司/チームがメリットを確認し、それに従ってください。
- コメントのいくつかはおそらく
/* Mystery parameter 3 */または/* 2015-02-09 AidanQuinn: Is this code ever called? */—これらは、同僚がコードを適切に文書化するか、潜在的なバグを修正する機会です。 - コミット前のレビュー中に、書き込んだコメントが不正確であることが判明した場合、同僚はコードが不明確であることがわかりました。
これを行うときは、リライトやリファクタリングを行わないでください。コメントの導入は、ほぼリスクがありません。何かを書き換える場合は、それらの変更を個別のコミットとして保持してください。
（ただし、このプロジェクトに着手する前に、コメントへの期待が妥当であることを確認してください。よくコメントされたコードの考え方が標準外の場合（ 例1 、 例2 ）、それからあなたは自分を馬鹿にするだけです。）
私はおよそ1年前にあなたと非常によく似た状況にあります。プログラミングの経験はほとんどありませんでしたが（OOや他のいくつかの言語は最初から知っていましたが）、教えている一人の人にはほとんど時間がありませんでした。彼はいつも役に立ちましたが、私は私が持っていたすべての質問をしたくないと感じました。
他の人はすでにここで非常に役立つものを提案しています（たとえば、単体テストを作成していますが、私自身の経験から、それは私にとって最初から少し「遠すぎる」か、またはコードの一部を自分でコメントすることになりますが、それは最初のポイント/質問によっては難しい場合があります。すぐに質問します）。次の点は私がしたことと私を助けたものを要約していますが、それはあなたの問題が正確にどこにあるかに大きく依存します。
また、C＃のコメントは本当に必要ないという@AK_にも同意する必要があります。それは100％正しいとは限りません（たとえば、リフレクションが多いコードなど、コメントが確実に役立つ領域があると思います）が、本質的にはそうです。名前の付いたメソッドと変数を使用して本当に「クリーンなコード」を作成し、コードの小さな「かみ傷」がたくさんある場合、それらはほとんど完全に不要です。これまでコードを読んでいたときにコメントが必要だと感じたときはいつでも、コードの機能を理解した後、コードの実行方法に非常に不満があり、適切なリファクタリングによってそもそもそれがはるかに明確になったのではないかと思いました。 編集：ここでは特にC＃について話していますコメント、ドキュメントではありません（それが別のドキュメントまたはXMLコメントであるかどうかにかかわらず）、ドキュメントは常に重要だと思います。
問題が正確に何であるかを特定し、それらを分類できるかどうか。つまり、言語自体にまだ問題があるか、特定の構文（ラムダ式とLINQ全般、またはリフレクションなど）を理解していないのですか？コードの行を理解しないと、メソッド/ブロック全体の機能が理解できないので、コメントを付けるのは難しいでしょう。むしろ、良い本を手に入れ（ 'C＃in a Nutshell'は私にとって良かったですが、 'C＃in Depth'も壮観だと聞きました）、あなたが遭遇したことを読んでください。これらの問題を事前に分類しておくと、一度に「大きなギャップ」を埋めたり、上司に質問したりすることができるため、これは簡単になります。多くの質問ではなく、単一の主題または最も一般的に使用される構成を説明することで、この領域で急速に大きな「ブースト」を得ることができます。
上記と並行して、「クリーンコーディング」とベストプラクティス（言語固有ではない）に慣れるようにしました。これの影響はすぐには現れないかもしれませんが、既存のものを拡張する必要があるとき、またはすべてが含まれているメソッドではなく、なぜそれほど多くの小さなメソッドが作成されたのか疑問に思ったとき、遅かれ早かれ報われるでしょう;-)
一般的な設計パターンを把握します。それらはあなたが読んでいるコードのあちこちに現れているかもしれません、そしてあなたがそれらを認識すればそれはすぐにあなたにa-ha瞬間を与えます。そこにあるコードの内容を理解していても、なぜこのように行われるのか不思議に思うかもしれません。自分でこれをすべて理解することは、多くの場合それほど簡単ではありません。
私はあなたの「スキル」について仮定しているので、上記のテキストを使わないでください。私はしばしば私の経験について話すことと「あなたに」話すことを誤って切り替えます。それは主に私が遭遇したこと、および私がしたことを意味します。他の人が言ったように、これは非常に良い経験になる可能性があり、あなた自身のものではなく、あなたが事前にあまり知らないコードを読むことは、仕事のほとんどの標準です。しかし、何が起こっているのかを最終的に把握し、この特定の「スキル」で自分が上達していることを認識することは、本当に満足のいくものです。これを機会にlotを本当に短い時間で学びましょう！ :)
あなたはおそらく彼に彼のスタイルを変えさせるつもりはないでしょう。
あなたができることは、たくさんの質問をし、答えを書き留めることです。
私は最後の仕事で巨大なコードベースを継承しましたが、ドキュメントやコメントはほとんどありません。だから私は同じ問題を30分試してみて、それでもそれがわからない場合は、それを書いたか、またはその使用方法を知っている人に尋ねます。それから私は彼が私に言ったことすべてを文書化します。ほとんどは私たちのドキュメントに入っていて、一部はコメントとしてコードに入っていました。 1年後、私は実質的にドキュメントの大部分を記述し、コードベースについて多くのことを知りました。
幸運を！
私も同じ問題を抱えていました。物理学者のIm学生で、プログラミングの経験が豊富です。私は多くの言語でプログラミングをしていましたが、優れたアプリケーションには何もありませんでした。
私はWeb開発者の仕事に応募しましたが、彼らはすぐにWebプログラミングのバックエンドに私を置きます。ボスがノードRESTアプリケーションのベースAPIを示したとき、私は捨てるつもりだったと思っていました。コールバックや奇妙な構文を持つ関数を見たことがありません。問題コードで何も説明していなければ、彼はいいえ、私は1か月間それを理解するのに悲しく、その間に別のフロントエンドでテストするためのCMSを作成します。
さて、私は一度に1行のコードに行き、私が知らないことすべてをグーグルしました。それで1週間が経過し、コードに精通しているので、フロントエンダーと共同作業を行うことができました。始めの私のコードはがらくたでしたが、その3か月後に私を設定しました！私はソフトウェアアーキテクトよりも優れた高速なコーディングを行っています。
あなたが学ぶのをやめないことをお勧めします！私のモト->学習を続け、落ち着いてください:)ボスが独立していることに依存せず、直接彼に尋ねますが、最も難しい問題だけです。あなた自身の研究によってそれを理解した後、あなたは幸せになるからです。そして、あなたが何か間違ったことを学ぶのをやめたとき、優れたプログラマーになる方法を毎日学ぶ。
ボスから学ぶ場合は、彼が自分の基準を設定するよりも上手になることはありません。ブラインドタイピングを学ぶVIMまたはVIM IDEのプラグイン、Linux wmii 、あなたはいつの日かボスを超えて、彼よりも上手になるでしょう！
他の人が述べたように、これは非常に一般的ですが、それはあなたがそれを吸い上げて耕す必要があることを意味しません。コードを深く理解する必要はありませんが、「ディープエンド」をより浅くするための具体的な方法があります。
- 手元のタスクに関連するコードでsomethingを見つけます。通常、検索が最も簡単なのは、GUIのボタンのラベルなど、ユーザーが表示できるものです。見つけた場所を書き留めます。これがアンカーポイントになります。
- 次に、1ステップ先のコードを検索し、それを書き留めます。誰がボタンを作成しますか？ボタンがクリックされたときにどのコードが呼び出されますか？
- ソース管理は、多くの場合、一歩離れたコードを見つけるのに役立ちます。表示しているコードがいつ追加または変更されたかを確認し、同時に他にチェックインされたものとその理由を確認します。
- 変更を加えるのに十分なだけ理解するまで繰り返します。さらに、何も不足していないことを確認するために1レベル深くなります。
- どこかに行き詰まった場合は、非常に具体的な質問をする必要があります。たとえば、「このボタンがどこからインスタンス化されるのかわかりません。」
私は同じような状況にあったと思います
上司は、理由がわからないという理由で（手がかりのないコードを確認することによって）汚い方法を学んでほしいと思うかもしれません。これは、他の回答で述べられているように、大学での1年間よりも1か月でより多くを学ぶ方法です。
これは、他の回答で述べられている「標準」です。コードのすべての行をすぐに理解しようとするよりも、どこから始めてどのように取り組み、何に焦点を当てるべきかについて心配する必要があります。適切なツールとコードをデバッグ/ステップ実行する方法について上司に尋ねます。この種の質問はあなたにいくつかのポイントを購入します。
定期的に上司に近づき、現在の状況についてフィードバックを得るようにします。そうすることで、上司が同じ状況でかなりの数の人を見て、彼らがどのようにしたかを理解していると仮定して、パーセンタイル用語で立っているというアイデアを得ることができます。
これを機会として、コードの理解が深まったら、最初に上司に尋ねると予想していたコメントを追加してください。
あなたが本当に彼に彼のコードにコメントを入れるように頼みたいと思うなら（私はそれをお勧めしません）本当にいくつかのコメントを使うことができる編集する必要があるコードを見つけることを勧めます（ほとんどは自明です）そして質問をしますこのように「私はここでこのコードを見ていて、[あなたが持っている問題]を理解しようとしているのですが、それを説明するのに役立つコメントを見つけることができませんでした。」基本的に、あなたがそれを理解することに努力を払ったことを示し、コメントがそこにあることで両方が利益を得ることができる理由を説明しようとします。
おそらく、適切に記述されたコードの90％はコメントを必要としません。最適化されてかなり緊張したコードの部分を文書化したいだけです。私はかつて会社で働いていましたが、変更したすべてのコードを文書化する必要がありました。基本的に、コメントはコードの可読性を損なうものであり、認識できないほど削除または変更されたコードを参照することが多かったためです。不十分なコメントに注意して、関数のデバッグに1週間を費やし、最終的に、そのようなフラグを「false」に設定することについて読み続けたコメントは、実際にはフラグを「true」に設定した問題全体であり、すべてが機能しました。それが想定されていたように。
これを丁寧に尋ねる方法があるとしても、上司がコード内のコメントについてどう思うかについては、2つの可能性があります。
彼のコード内のコメントは良いものになるでしょう、または
彼のコード内のそのコメントは、良いものではありません。
あなたのボスが彼のコードのコメントが持つのは良いことではないと考えている場合（そしてこれには非常に良い議論があります、すなわちコードはドキュメントであるはずです、および実際にそれを行うコード、）と同じくらい正確かつ明確に何かを規定するドキュメントはありません。その後、何も起こりません。
さて、もしあなたのボスが彼のコードのコメントが良いことだと思っているなら、彼はあなたに彼のコードを研究し、それがどのように機能するかを理解し、そして彼にコメントを追加することを続行するように言うかなりのチャンスがあります。コードyourself。 （これについても非常に良い議論があります。つまり、学習する必要がある、そして彼の時間は定義によりあなたより価値がある。）
したがって、これを行う準備ができていない限り、何も言わない方がよいでしょう。
だから私が物事を把握するまで私の助けになる何かだけ、上司が彼に与えたコードにコメントを入れるように頼むことができますか？
コードを理解できない場合、なぜコメントがあなたの解決策であると思いますか？
彼のプログラミングスタイルはわかりませんが、関数や変数の名前が誤解を招くと、コードの理解が非常に難しくなります。しかし、名前と関数、さらにはプログラムの構成（クラス、メソッド、プロパティ...）がコードを理解できるようにするものである場合、コードは実際にそれ自体と対話します。
彼にプログラムアーキテクチャを尋ねて、彼に何かを要求したい場合は、関数のより意味のある名前を要求する方がよいでしょう。それは彼にとってはより便利です。
コードにコメントを入れて、何かが書かれた理由を理解したい場合は、おそらく（新しいと考えて）ビジネスニーズをまだ理解していません。私はあなたがすべての構文を知っていてコードを読むことができると確信していますが、いくつかのコードの目的を知らなければ、少し迷ってしまいます。
頭に浮かぶのは、ペアプログラミングです。あなたの上司はあなたの進歩に感銘を受けているので、彼と一緒に働くことを提案できます。これは、長期的にはあなたの両方に役立ちます。上司は当然のことを説明しなければならないことに気づき、ビジネスについてさらに学ぶことができます。
これが私の問題の0.02ドルです。私は排他的な答えを提案しているわけではありません。ここで述べられていることの多くは非常に関連があります。
上司が自分のコードの一部をコメントするよりもコメントする方が簡単で時間がかからないように、ソーシャルエンジニアリングを少し調整してみます。
大きなリスクを冒して彼を悩ませるのであれば、これは非常に簡単です。しかし、私たちはそうしたくありません。 （付記：彼があなたにコメントを書いたり口述したりせずに何もできないだけで失敗するかもしれません、あなたは彼にそれについて延々と主張し、苛立たせます。）
それでは代替案は何ですか？状況に応じていくつかのアイデア。
オプション1
- 時間をかけて彼のコードの一部をXとして理解してください。
- ここで、Yが誤解になる合理的な方法を考えてみましょう。
- あなたが現在それを理解しようとしていることを上司に（電子メールを介して、または朝食をとって言ってください）。
- コードの意味が明確ではないが、Yとして理解していることをコメントに追加します。このコメントを彼に見えるようにしてみてください-しかし、一生懸命にしないでください！
- Y-と仮定して行動し、sureを上司があなたの行動に気づくようにします（したがって、誤った仮定で長時間仕事を無駄にしないでください）。
- 上司が率先してあなたを修正する必要があります。この時点で、「このコードに間違った仮定をしないようにコメントが2つあることを本当に望みます。自分のために追加したコメントを修正します。一般的な説明で私を助けてくれると思いますか？これ以上のコードの一部ですか？私は正確な意図を理解するのに十分な経験がありません、そして私はほんの数文でうまくいくでしょう。」か何か..
オプション2
トレーニング中です。彼との（追加？）固定頻度の毎週の会議を手配するようにしてください。この会議でコードをいくつか検討しますが、彼がすべての行を説明する必要がないように十分な準備をする必要があります。いつか-うまくいけば-コメントを追加しただけで会議をスキップできることに気付くでしょう。
オプション3
別の同僚に、あなたと同じコードの一部を理解してもらいましょう。どちらも上司に異なるタイミングで接近し、同じ質問をします。これは、彼が何かをしていないことを彼に気付かせるための確実な方法です...しかし、誰もが同じプロジェクトで役立つ同僚の贅沢を持っているわけではありません。
20年のソフトウェアエンジニアとして、主に安全関連（SF-PD）に取り組んでいるため、上司はあなたの例になりたい人ではないかもしれません。コメントの欠如は、仕事を適切に行う方法を学んだことのない独学のアマチュアコーダー、または経験の浅いエンジニアのいずれかの兆候です。あるいは、時間のないエンジニアでも、締め切りと便宜のために、コードに恐ろしいことがあるかもしれません。 ;）それは確かにすべての有能なソフトウェアエンジニアのためのアンチパターンです。
あなたの上司は非常に優れたコーダーかもしれませんが、彼は優れたソフトウェアエンジニアではないようです。エンジニアは、集団での経験を利用して、他の人々がすでに陥っている落とし穴を回避します。効果的なコメントは、応力分析が機械工学の集団的経験の一部であるのと同じように、ソフトウェアの集団的経験の一部です。効果的なコメントと見なされるのはより流動的ですが、それは間違いなく経験から得られるものです。
最も基本的なことは、コメントはコード行が何をするかを述べてはならないということです。関数の機能を説明するコメントが不要な場合もあります（特にC＃の場合）。ドロスの中から重要なものを見つけることができないので、オーバーコメントは同様に効果がありません（そして経験の欠如へのポインター）。初心者でも、コードの「内容」を理解する作業を続けている可能性があります。そのためには、コードの実行内容を読んで理解する必要があります。
ただし、コメントの重要な点は、[〜＃〜] why [〜＃〜]コード行または関数が何を行うかを示していることです。モジュールYの前にモジュールXをセットアップする必要がありますか？戻りコードをチェックしてファイルが既に開いているかどうかを確認することは重要ですか、それとも他の場所でチェックされているため、意図的に戻りコードを無視していますか？コードの「理由」は、経験に関係なくすべての人に関係します。また、何か特別な方法を実行する正当な理由を忘れた6か月後にも、彼に関係するようになります。コメントは他の人のためだけではなく、将来あなたを助けるためにもあります。
上司に迷惑をかけたくない場合は、賢い質問をしてください。 「なぜ」について尋ねることに焦点を当て、自分で「何」を考え出そうとします（それが本当に不明瞭でない限り）。 R-ing TFMから見つけることができなかった種類の質問でなければ、上司は質問されてもかまいません。そして、優れたエンジニアは、他のエンジニアの生活を大幅に楽にするような少しのコストで何かをするように求められることを気にしません。 （コードベース全体にコメントを埋め戻すように彼に頼まないでください！;）