上司は、コードのナレーション付きの行ごとの英語の説明を望んでいます
私は、上司が読み、フォローできるようにしたい、1行ずつ（または必要に応じて、たとえば、画像ごとなど）の説明または解説をするように特に求められました。
彼はプログラマーではないので、コードをたどることができないので、すべてを英語に翻訳したいと考えています。
誰かが以前にこれを行うように頼まれましたか？
私はすべてのソースコードにコメントし、 JSDoc を使用してすべての関数、変数などの完全なドキュメントを生成し、実装例と、全体を通してコメント付きの完全に機能するデモを含めました。
プログラマーでない人のためにコードにコメントするために他に何かできることはありますか？
これは妥当な要求ではありませんか？
更新
最後に、なぜ彼が求めていた時間を有効に活用できなかったのかを説明することができました。彼は適度な男で、私の仕事が何をしているのか理解していませんでした。彼がこの投稿を見たとき、彼はそれが通常の要求ではないことをすぐに理解したと思います。
私は、他のプログラマーがフォローするのに適したドキュメント（JSDocとインラインコメント、および技術的な問題に関する追加のメモ）と、上司がフォローするプログラムのメインロジックの非常に広範なフローチャート図を提供しました。
結局、すべての当事者が満足し、私たちは次に進みました。
いいえ、それは合理的な要求ではありません！
TALK HIM OUT OF IT、または誰か他の人に話してもらいます。これは不合理なアイデアです。実行可能なことは非常に高価ですが、実際に実行することはできません。関数とサブルーチンの概要は妥当ですが、すべてのコード行を「説明」するのは適切ではありません。彼が手で言語を読むことを学ぶことは、それを行うよりも効果的でしょう。
次に求められるのは、数式などを英語のテキストに翻訳することです。その可能性は確かにありますがエラーと誤解の余地が多くありますであり、絶対に行うべきではありません。コードを英語に「翻訳」するのと同じです。
設計ドキュメント はありますか？それらは、コードが何をするかについての英語の説明です。非プログラミングマネージャーはそれ以上のものを必要とすべきではありません。
年間最優秀マイクロマネージャー賞はありますか？あなたの上司は指名に値するようです。彼がコードを行ごとに理解する必要があると信じているが、コードを直接読み取る方法を学びたくない人は、想像できる限りマイクロマネージャーと同じくらい完璧です。
開発者であることの利点の1つは、コードを理解することの難しさにより、少なくとも詳細な実装レベルでは、少なくとも非技術的な管理により、ある程度のマイクロ管理が妨げられることです。そのレベルで彼らの頭の上。しかし、上司の天才はシリコンカーテンを粉砕する方法を見つけるかもしれません。
そして、ボーナスとして、それは翻訳を行う開発者の多大な時間を浪費しますbefore彼は英語の翻訳を使用してさまざまな改善を提案し始めます（プログラマーよりも優れたコーディング方法を知っていると思います） 、彼はコードをreadできず、誰かがそれを翻訳するとすぐに彼の知恵を共有できるようになりますすべての行が翻訳されましたか？）.
だから、いや、それは理にかなった要求ではなく、私はそれをこれまで聞いたことがない。そして私はあなたのために感じます。管理ツールとしてコード変換を使い始めると、それはおそらく残酷な作業場所（つまり、もっと残忍な作業場所）になるため、誰もが静かに別の仕事を探す必要があると思います。
プラス面では、状況に応じて名前が付けられた新しいアンチパターンを入手できるでしょうか？モンティPythonスキットが、英語を話せない人と、コミカルなハンガリー語のフレーズブックを使って英語を話そうとしているところです。誤った翻訳？
彼と一緒に座って、10行のコードについて話します。あなたが両方とも彼が望んだ範囲でそれを理解することに同意するまで、すべての詳細を説明してください。
たぶん、この経験が彼の求めるものすべてかもしれません。あなたの仕事があなたにどのように見えるか、そしてあなたの視点からソフトウェアがどのように見えるかの単なる印象です。それは私の本では良いことです。
この後も彼はあなたに続けて欲しいと言います：私が尋ねなければならなかった質問の数に注意してください;質問することができずにこれらすべてを説明しなければならなかったとしたら、どうすれば何を含め、何を除外すべきかを知ることができたでしょうか。結果が役立つまでにどのくらいの時間がかかりましたか？このようにして、何行にしてほしいですか？
それは妥当な要求ではないと思います。ソースコードは英語（またはそのほかの言語）で読むことを意図していません。
多分彼はあなたがあなたのコードに彼が承認していないか気付いていないことをさせようとしているのではないかと恐れています。そうだとしたら、何かできることはないと思います。ドキュメントを書くか、コードを監査するために誰かを雇うように彼/彼女を説得する必要があるでしょう。
それは本当にとても簡単です：
- プログラマーとしてのスキルのために採用されました
- あなたの上司はこれらのスキルを持っていません
- エルゴ、あなたの上司はあなたが何をしているかを完全に理解できると合理的に期待すべきではありません
私は前の仕事でこれと同様の経験をしました。私のマネージャーは会計士であり（したがって、非常に低レベルの詳細指向でした）、プログラミングを理解しておらず、真に信頼していませんでした。彼女は、非技術者として、私が書いたものの特徴を把握できると期待すべきではないことを理解できませんでした。多くの過剰なドキュメントの要求と、コードを管理および変更する方法について技術者以外のユーザーをトレーニングする要求（そうです、本当に）の後、私は彼女を騙そうとするのをやめ、完全に拒否しました。私が説明に使用した類推は単純でした：
- 私は会計士ではありません
- すべての取引やアカウントへの転記を理解することは期待しない
- これは、単に私がそれらを理解していないために、アカウントが間違っている、または信頼できないことを意味するのではありません
- これはtrustingによって作成されました。
結局のところ、これは私にはこのように聞こえます。従業員を信頼するのが難しいマネージャー。または彼らが去ることを恐れており、これはそれを緩和する効果的な方法であると考えています。
これに対する唯一の解決策は、座って、なぜこれが意味をなさないのかを説明することです。コードを理解し、マネージャーのスキルではなく、あなたと同様のスキルを持つ誰かがコードを理解できるようにするのはyourジョブです。彼らにこのスレッドを表示するのは良い考えかもしれません（または、性格によっては本当にひどいものです）。
行ごとに、ばかげています。私が提案するかもしれないことは、コメントからドキュメントを生成し、彼にそれを与えることを提供することです。これは、私がこれまで取り組んできた多くのカナダ政府の助成金と監査には十分でした。
彼は1行ずつは取得しませんが、メソッドごとに取得しますが、still必要以上に細かくする必要があります。
プラットフォームに応じて、いくつかの既存のソリューション：
興味深いアプリケーションのコード全体を英語に翻訳するよりも、コードを読むことを学ぶ方がはるかに速くなります。その上、私たちはCOBOLでそれを試しましたが、それはまったく役に立ちませんでした。彼が学びたくないが、彼の無知を他の誰かの問題にしたいだけの場合、あなたは真剣に先のとがった頭の上司を持っています。
あなたの技術的専門知識を使って上司を追求してください。
- これを行うには、最初にコードを作成するのと同じくらい時間がかかることを彼に知らせてください（自由に長くしてください）。
- このドキュメントを最新の状態にする必要があるかどうかを尋ねます。すべてのコーディング変更に少なくとも2倍の時間がかかることを通知します。
- あなたまたは他の誰かがバグを見つけた場合は、すぐに修正するか、疑似コーディングが完了するまで待つかを彼に尋ねます。 ＃1と＃2を思い出させる。
すべての悪い解決策の提案と同様に、問題を特定することをお勧めします。たぶんあなたの上司は上級管理職による技術的な質問に襲われており、答えられないので恥ずかしいと感じています。彼が最も懸念しているコードの特定のセクションが1つある可能性があるため、この大規模な事業をその領域のみに制限できます。
サンプルを提出することで、コーディングのしくみ（ループとは何か、これらのすべての項目に対して何が行われるのか）がわからない場合は、どの言語で記述されているかは問題ではないという結論に達するかもしれません。パワーユーザーの観点からアプリケーションを理解する必要はありません。あなたが本当のコード/ヒントを書いていることを彼に知らせるのは公平だと思います-私は別の仕事を探しています。
どうして？
行ごとのコメントは合理的ではありませんが、ここで私が尋ねることは次のとおりです：なぜこれが必要なのですか？
それは...
- あなたはソフトウェアが何をしているのか（必ずしもそうではない）を完全に理解したいですか？
- 私が去ったら、別のプログラマーがプロジェクトをピックアップできるようにしたいですか？
- 私が本当の仕事をしているのを見たいですか？
この要求の背後には合理的な欲求があるかもしれませんが、それを理解してそのニーズを満たすことで上司を幸せにすることができるかもしれません。
更新
に基づく Mikey'sコメント、多分私はこれをあまりにも率直に述べました。文字通り「なぜこれが必要なのか」と言う必要があるという意味ではありません。ただそれを見つける必要がありますです。言葉遣いや声のトーンが大きな違いを生みます。具体的には、次のように言うことができます。
「私は、コードの1行ごとに説明を求めるリクエストについて検討してきました。そのようにすることは少し珍しいことです。私の仕事についてあなたにうまく伝えられていないことがあるのではないかと思っていました。私たちのコード、または私が何をしているかについて本当に理解したいことは何ですか？ここで何を達成しようとしているのですか？」
もちろん、あなたの上司が全く無理なのは可能です。しかし、彼がこの要求がどれほど風変わりであるかを知らず、何らかの合理的な目標を念頭に置いている可能性が高いです。
そうでない場合は、履歴書を磨き始めます。 :)
行ごとの翻訳でさえ、コードの各行の意味を効果的に伝えません。プログラマーがコード行を理解することは、常に多くの要因のコンテキストにあります。マルチスレッドコードのようなものに入ると、英語の翻訳は生のコードよりも意味がありません。複数の関数/ファイルにまたがる機能について考えます。他のコードを大量に説明しなければ、意味のないコードもあります。依存性注入に関連するさまざまな部分を「行ごと」に説明してみてください。そうすれば、私の意味がわかります。神機能の手続き型コードを超えるものは、英語の翻訳を理解するためだけに大量のプログラミング知識を必要とします。また、if/else意思決定ステートメントのような単純なものも見てください。次の行は実行時データに依存しているため、行ごとにありません。次の行は、いくつかの可能性の1つになる可能性があります。 アプリケーションの機能を説明するまでに、PMプログラマーになり、どちらも5歳になります。
以前はプログラミングを教えていたので、それを試してみるのはとても幸せです。
彼は交渉した額を上回っていることがすぐにわかります。私はlike物事を説明する：-）なので、私は悲しくなります。
あなたの「上司」を指すとき、これは「あなた/あなたのチームを担当する中間管理職」ですか？またはあなたの会社の所有者ですか？ 「時間単位」または「給与」で支払われますか？
上司が責任を負う中間層のマネージャーである場合は、上司に話してください。上司の要件を満たすために、会社の生産性がそれの1/3に削減されることを指摘してください。
上司が「小切手に署名する男」である場合、上司に同じことをもっと外交的に説明します。あなたの仕事は「コードを書く」から「コードを書く、コードの説明を書く、説明を説明する」になりました。
文芸的プログラミングを試す良い機会のように思えます。グーグルそれ。 :)
しかし...それは必ずしも全体的に不合理な要求ではありません。あなたの仕事の一部（より重要な部分はimo）は、アルゴリズムを他の開発者、および必要に応じて非技術者に伝えることです。コミュニケーションが取れない孤独な天才プログラマーは常に問題を抱えていると思います。
そのためには、コードを明確にする必要があります（つまり、真に自己文書化または十分に文書化されており、「自己文書化」とは、変数と関数にoneの意味または責任があり、それらの名前が反映されていることを意味します）それは明らかに）。あなたの上司は彼の要求に正当な理由があるかもしれません。 多分（私はここで推測しているだけです）あなたまたはあなたの前任者は不可解で壊れやすいコードの評判を持っています、そしてこれはあなたの上司の救済です。それは少し極端ですが、あなたにとって役に立つ演習かもしれません。私は彼がより良いドキュメントを書くには時間がかかることを知っていると思います（そうしないと、彼は教育を受ける必要があります-それはちょうど用語の論文を書くのと同じです：読むより書くのに時間がかかります）。
フローチャートはおそらく彼にとってより有益でしょう。これは確かに珍しい要求であり、マネージャーとしての彼についてはあまり言いません。
上司があなたが書いたコードを理解するためにある程度の時間を費やすことをいとわないという事実は、あなたの利益のために使うことができます。彼にキュウリを紹介してみてください： http://cukes.info/
上司にBDDテストを記述してもらいます。
英語の美しさは美しく難読化されていることです。これを有利に使用すると、この種の要求に再度対処する必要がなくなる可能性があります。私はサンプルとしてコードの小さな部分を取り上げますが、それは非常に抽象化されており、まったく理解しにくいものです。次に、プログラミングブックの章にそれを書いているかのように、コメントをテクニカル英語で書きます。追跡する時間が長く、複雑であるほど良いです。この1つの機能を文書化するのにかかった時間を彼に教えてください。次に、実際のコードベースの1％の1/10にすぎないことを説明します（可能であれば、コード行に基づく実際の数値を使用します。これはおそらくこれよりも悪いでしょう）。彼が英語の訳が言っていることの手がかりがなく、このレベルのドキュメンテーションを行うのに20,000人時間かかると気づいたとき、彼はかなり迅速に後退するでしょう。しかし、彼の仕事を成し遂げるために非常に真剣に努力すること。あなたがそれを引き出すことができず、彼があなたが彼を演じていると疑っているなら、これを試さないでください。
これは特別な休日の問題の先のとがったボス Dilbert ストリップの候補のようです！彼の要求は一見サウンドは確かに妥当ではありません。
ユーモアはさておき、本当にが何を必要としているのか、そしてその理由を見つけて、それを与えるために何ドルまたは何時間かかるのかを彼にアドバイスし、そして、彼がそれに多くのお金を使いたいかどうか彼に決めさせます。
あなた自身については、彼の一見奇妙な要求を満たすのにかかる時間を数え、あなたがあなたを扱いたいと思っている雇用主のために働く新しい仕事を見つけるのにその時間の一部を投資する方がいいのではないかどうかを判断しますプロとして！
彼をあなたのオフィスに連れて行き、あなたのコードのツアーを彼に見せてください。
彼はばかげた要求をしたことの途中で気づくでしょう、そして彼は立ち去り、二度とあなたを悩ませることはありません。
彼があなたのコードを理解しようとするのを手助けするという彼の要求に応えないなら、彼はあなたを突くために異なるが不条理な方法を見つけるでしょう。
これは、緩和策が摩耗よりも効果的な場合です。
これを行う「Language X to English」という翻訳者がいれば非常にいいでしょう。その後、にやにや笑って言うことができます、ボス、あなたはすぐにそれを持っているでしょう。次に、数メガバイトのテキストを含むメールが届きます。
- Aを20要素の新しい整数配列とします。
- Xを整数を格納する変数とします。
- Xを0に設定
- Xは20未満ですが、次の2行で規定されていることを行います
- インデックスxを持つaの配列要素を、引数x + 1でnThPrimeを呼び出した結果に設定します
- xを1増やす
- ....
別のオプションは、今後 シェークスピア でのプログラミングを提案することです。
彼はそれを気にしないでください。ソフトウェア開発では実装が変更される可能性があることを彼に伝えます。イベントのデザインは変更される場合があります。情報の隠蔽、カプセル化、抽象化について彼に話してください。
彼は、チームの一員として、コードのクライアントとして、より広い意味で、コードが行うことの明確で高レベルの抽象化でのみ機能する必要があります。コードの任意のレイヤーが他の誰かのコードの別のレイヤーと連携するのと同じように。それ以上のことを知っていても、彼を遅くするだけであり、あなたのコードの内部の仕組みに基づいて推測をする危険を冒します。コードに変更を加えなければならない場合、それらに基づいてシステムやプロセスを構築すると問題が発生すると、これらの仮定は保持されなくなります。
また、この種の作業を行う必要があると、効率が低下します。 2つの異なる場所で後続の変更を行う必要があるだけでなく、作業意欲にも悪影響を及ぼし、出力がさらに低下します。
上司は、コードのナレーション付きの行ごとの英語の説明を望んでいます
タフ。
彼はプログラマーではないので、コードをたどることができないので、すべてを英語に翻訳したいと考えています。
彼がプログラマーでない場合、彼はコードを読んではいけません。 まったく
代わりに、高レベルのドキュメントを提供してください。
これは妥当な要求ではありませんか？
番号。
おそらく、このリクエストは [〜＃〜] antlr [〜＃〜] のようなことを学ぶ良い機会です。 ANTLRを取り、言語の文法を取り、すべてのコードを解析し、 [〜＃〜] ast [〜＃〜] をトラバースして、すべてのノードについてテンプレートベースの説明を生成するので、i++はincrease i by 1 using postfix increment operator。それは本当に面白いはずです。上司はこのツールをビルドスクリプトに含めることもできます。そのため、変更を加えるたびに、新しいバージョンの動作を説明する約20 MBの電子メールが届きます。
追伸冗談です、彼はバカです。
プログラマーとして、あなたは本当に「2つの」仕事をしています。
1つ目は、優れたプログラムを作成することです。 2つ目は、社内外の顧客にそれらを「販売」することです。
あなたの上司の要求はあなたの最初の仕事を「傷つけます」。プログラムの文書化には、より多くの時間がかかります。一方、彼は実際にあなたの「二番目の」仕事にあなたを一生懸命働かせています。
あなたの上司は、HISの利益のために、そしておそらく会社の内外で彼が取り扱わなければならない人々のために、プログラムを英語で文書化するように求めています。彼が彼の仕事をするのを助けるならば、あなたが彼にもっと多くのハードウェア、人員、または昇給のためのお金を求めるとき、それは長期的にあなたの利益のために働くはずです。結局、彼はあなたにもっと仕事をするように頼んだ。
私は [〜＃〜] bdd [〜＃〜] がこの問題に適していると思います。今後の参考のために。
BDDの使用例は、人が読めるドキュメントとして記述され、自動化された機能テストに変換されます。
cucumber ？などの動作主導の設計フレームワークを使用して、いくつかの受け入れテストを記述できます。それはコードを説明しません。それが何をするのか、自然言語で説明します。また、実行可能であるという利点もあり、ドキュメントが最新であることを常に確認できます。そうでない場合、テストランナーは赤になります。
紹介ビデオをご覧ください。多分それはあなたが新しい上司を見つける間、良い転用です... ;-)
これは不当な要求であることに同意しますが、上司は Docco の出力のようなものを高く評価するかもしれません。これにより、コードと行ごとのコメントまたは句ごとのコメントが2列のHTMLに分離されます。片側にコードがあり、反対側に散文がある出力。もちろん、コメントは自分で入力する必要がありますが、技術に詳しくない読者にとっても、プレゼンテーションはかなりいい印象です。たとえば、 nderscore.jsの注釈付きコードの行ごとにコメント化されたセクション を参照してください。 Pythonとシェルスクリプトのバージョンもあります。
あなたの上司は知らされておらず、脅されているだけかもしれませんが、実際には合理的な人物です。もしそうなら、彼/彼女との推論はうまくいくかもしれません-「彼が本当に望んでいるもの」を提供することを約束するカジュアルな会話、すなわち;プログラムが何をしているかについての散文ガイド。
「マイウェイまたはハイウェイ」に分類される場合は、すぐにガスを確認してください。
上司は、自分が管理している人々の行動を理解しておらず、彼らが生み出す結果を理解するための経歴もないという事実に、ほぼ間違いなく悩まされています。
私は彼がこの解決策を非常に徹底的に考えていたのではないかと思います。おそらく一見すると彼には理にかなっているように思われました。しかし、それは主に、プログラミングコードが実際に何であるかを理解していないためです。
プログラマーはこのリクエストの不条理を理解しますが、言語を過ぎてしまうと直ぐにわかるのは、同じように暗号化されたアルゴリズムだけが明らかになるためです。
// Set s to the first address in the server list
server_info *s = cmd->servers;
// Loop until s is NULL
while (s) {
// call the server's init function passing our current ID and address
s->init(proc->id,*addr);
// call log::info with our custom message
log::info("Starting server %s",s->name);
// Set s to the value returned by the server's next() function
s=s->next();
} // end of loop
ここでの問題は、コメントが各行の機能を説明しているにもかかわらず、すべての影響を理解しない限り、コードが実際に何をするのかわからないということです。あなたがプログラマーで、このパターンを以前に見たことがあるかどうかは明らかです。しかし、売り上げだけを理解している人にこれを見せてください。そうすれば、彼はコメントを読んだ後、以前と同じように混乱します。
上司に基本的なプログラミングを教えることで、実際に時間を節約できます。彼があなたのコードを読みたければ、そうすることができるツールを彼に与えてください。ほとんどの言語は構文的にはかなりコンパクトであり、構造の学習は1〜2時間しかかかりません。彼はほぼ間違いなく数日後にあきらめるでしょうが、少なくとも彼は何を伝えているのかを知っているでしょう、そしてもっと重要なことにwhy彼はあなたのコードを読みたくないのです。
なぜ、またはリクエストの動機が何であるかを尋ねてから、関連するコストを正直に決定し、リクエスト元と共有します。これが不当で悪意のある要求である可能性がある場合は、別の仕事を見つけてください。
まず、ここでの目標は何ですか。彼がどんな説明をするにしても、別の方法を考え出す。
次に、これにかかる時間の見積もりを、まとめるのにかかる時間と実行にかかる時間の両方の観点から提供します。あなたの両方の時間が他の何かをすることに費やされていないかどうか、繊細に表現された言葉で尋ねてください。
まず、アプリのコードが何千行あるかを彼に伝えます。
それが失敗した場合は、既に示唆したように、コード全体をナレーションで説明するときに彼が期待するはずのサンプルを提供してください。それは彼を満足させるはずです。
彼がしつこい場合は、新しい仕事を探し始めます。
ところで、これは実際にプロジェクトマネージャーが介入して上司に説明する必要があるケースです。この詳細レベルは全員の利益にはなりません。
これは不合理な考えではなく、かなり論理的です。コードをチェックして、そこに壊れるものがあるかどうかを確認するのが彼女の義務です。
シンプルにするために最善を尽くすことができるように、それはあなた次第です。誰かがすでに提案したように、シンプルなUMLダイアグラムを使用して優れた設計ドキュメントを作成するのが最善の方法です。行ごとにコメントする必要は必ずしもありません。エンドユーザー（または顧客）として、誰かが要求を出すことができます。今、それをどのように満たすか（デザインドキュメントまたはエンドユーザードキュメントを作成するか、行ごとにコメントを書く）はあなた次第です。
私の仕事でも、新会社に入社したときは、リーダーから指示されました。新しい場所にいるときは、評判を築くために少し時間が必要ですが、そのときにそのような要求が来ます。 [〜＃〜] uml [〜＃〜] 図をモジュールごとに作成することで、それを実現しました。
行ごとに説明すると、コーディングファイルのサイズが確実に大きくなります。これが、ドキュメントを個別に紹介する理由です。
とにかく、彼が行ごとの非常に詳細な説明を必要とする場合は、コーディングに使用したプログラミング言語のドキュメントを添付し、そこから参照するように依頼します（たとえば、Java次に、JavaTM 2 Platform、Standard Edition、v 1.4.2 API Specificationを参照してください。
間違いなくこれは機能します。 :-)
コード[〜＃〜] is [〜＃〜]英語はすでに、「for」、「if」、「else」など。特定の文字を検索して置換するだけです。たとえば、「>」を「より大きい」に置き換えます。
"もちろん問題ありません"
JavaScriptアプリケーション<!DOCTYPE html>の1行目から始めます
そして、CPUのエレクトロニクスまでドリルダウンします...
コードのバイトごとにこれを行います。
Doctypeとは何かを説明し、目的を説明し、履歴を説明し、代替案を説明します。
問題？
私見...彼がその仕事を成し遂げる責任があるなら、彼はそれがどのように機能するかを知っているべきです... :)
私はあなたがそれをやるよりも多いと言いますが、完了するのにx週間かかります、そして彼はあなたがそれをしたい/あなたがそれをする必要があると確信していますか？
きっと彼はあなたが他の場所で時間を費やしたほうがいいことに気づくでしょう？
コードのコメントで、コードのほぼすべての行に「英語」の説明を作成します。私はこれを不当な負担とは考えていません。確かにあなたがそれを説明する方法は、少し怪しいようです。それ以上のものは、不当な上司がいるか、仕事上の関係に問題がある可能性があるという赤信号です。
このようなばかげた何かを望んでいるマネージャーがいつか私たち全員にいます。中途半端にならないようにするのは難しいですが、しないことが重要です。彼はただ掘り下げるだけです。たぶん、彼を長所と短所のリストにして、彼と一緒にそれらを通過することができます。私の意見では、反対側の最初の項目は、適切なコードが自己文書化であることです。しかし、彼らはこれに陥ることはほとんどありません。
これは実際にはをするのは馬鹿げたことかもしれませんが、使用している言語を英語の「プロポーズ」にコンパイルするコンパイラをまとめることができますか？コンパイラーを介してコードを実行し、wcのようなコードを使用してコードの行数を把握し、上司がコードを使用できるようにすることができます（おそらく、印刷すると脅迫します）。
彼にこの質問とあなたが得たすべての答えを示すことは、彼が無理であることを彼が理解するのに役立つと私は言うでしょう！ですから、ここですべての答えを確認するように依頼してください。もちろん、不快で敬意を表さない方法で。彼は開発者のやり方を理解するでしょう！
さらに、すでに述べた多くの人々のように、図を使ってみてください。しかし、ここでも、ここで与えられた応答を彼に示すことを真剣に考えてください！
まず、リクエストの範囲を確立する必要があります。ボススターの下の机の上をモンスターよりも怖くしないようにする必要があります。
それ以上ですか：//メソッドは顧客を取得します。以上：// intとは何か、「void」の意味、および英語の概念に書き直された数学を含む、いくつかの長い詳細なプログラミングの説明？
おそらくそれはその中間にあります。
リクエストが極端すぎることが判明した場合：
プログラマーは小さなことのように思えますが、最も一般的なコードの意味を除いて、プログラマーはこのように物事をしたり自分自身を表現したりする訓練を受けていないことを上司に説明することをお勧めします。複雑なアイデアを素人に伝えるように訓練された人々がいます。彼らはテクニカルライターと呼ばれています。
私が思う1つの問題は、十分に対処されていないか、まったく対処されていません。これを行うには、コードが記述されているときに行う必要があります。納期を守ろうとすると、これがどれだけの時間を食い尽くすか知っていますか？
これらのタイプのコメントをコードに含めてはならないので、これを機能させるための良い方法やツール（私が知っている）はありません。
これはメンテナンスの悪夢です。コードを生成するときに何らかの方法でこれを回避することがわかったとしても、コードがメンテナンスに入ると、コメントはどのように維持されますか？
チャットの後で上司がまだ話せない場合は、新しい仕事を探してください。コウモリのクレイジーなアイデアが1つしかない人は、ユニコーンよりも珍しいです。
そして、この人物がコードファイルを開いている場合は、適切なソース管理を行っていただければ幸いです。
理想的には、すべてのコードは、同僚または上司のいずれかにとって読みやすく、理解可能である必要があります。上司がこれを望んでいる場合、コードは十分に表現力がなく、意図を十分に伝えていません。コードにナレーションを付けないでください。できるだけ英語のナレーションに似せるようにコードを記述してください。詳細については、ドメイン固有言語（DSL）を参照してください。
いくつかのリンク：
私は彼にビデオを見せますハンガリー語（Küküllőmentilegényes）フォークダンスとのクイックソートそして、どれだけ長く説明しますあなたが持っているすべてのコード行に対してこれを行うには時間がかかります。
それは非常に不合理な要求です。あなたはコードとプログラムを書くために雇われており、あなたが書いたドキュメントは、上司や従業員ではなく、同じプロジェクトに取り組んでいる他の開発者やプログラマーを助けるためのものです。
えっと...
仕様からコードを作成しましたか？要件は正しく文書化されましたか？
彼が半分まともなマネージャーである場合、彼は「これは要件を満たしていますか？」と尋ねる必要があります。
上記に「はい」と答えた場合は、それらのドキュメントとすでに述べたものを彼に提供します。それでも彼がさらに欲しければ、彼はばかであり、明らかに開発チームを管理すべきではありません。
そして、その愚か者が「よく何を知っているのか」が戻る前に...私はこのスレッドだけで少なくとも50年の経験を組み合わせているに違いない。
マネージャーの役割：1.目標を特定して割り当てる。 2.それらが正しく実行されていることを確認します。 3.すでに回答されているはずの愚かな質問をしないでください。
正直なところ、すでに構築されたソリューションがある場合、彼は何が書かれているかを知っているはずです。もし彼があなたが何をしているのかわからないのなら、彼の上にあるsmoeoneが彼のチームが今何をしているかの詳細を要求したと思います。
本当に賢く、ソリューションをビジネスプランにリンクし、ビジネスの主要な目標をどこで満たしているかを示し、ラインマネージャーに詳細を伝え、自分のマネージャーはあなたを理解できないようだと述べます。
あなたはおそらく彼の仕事を得るでしょう。
私は具体的に、上司が読み、フォローできるようにしたい、行ごと（または必要に応じて、たとえば画像ごとなど）の説明/コメントを提供するように求められました。
彼にフローチャートの笑いを与えてください...
それか、ユーザードキュメントを求めているのでしょうか。
私はまた、上司にこれを行うにはX時間かかることを指摘します。彼がこれが何をするかを見た後、彼があなたに続けるように頼んだら、私は驚かれることでしょう。
また、あなたの機能のコードレビューに彼/彼女を招待します。彼/彼女が何かを理解できるわけではありませんが、これはあなたとあなたのチームがあなたのコードを口頭化する必要がないように内部で行うことであることを理解するためだけです。あなたの上司がこれを求めている場合、私の直感は、彼/彼女があなたのチームを信頼していないか、彼らがデューデリジェンスを取っていると信頼していると私に言っています。彼/彼女にコードレビューを通して座らせることによって、それはデューデリジェンスと彼/彼女がうまくいけばあなたを一人にしておくことを実証するでしょう。
はい、それは私たちにとって合理的な要求ではないことに同意しますが、多分彼はそれがどのように機能するかを知りたいと思っています。ですから、プログラマーではない人にとっては、 flowchart を使用します。上司が全体像を把握できるように、またはフローチャートで必要に応じて、彼の要件に応じて詳細に入ることができます。利用可能な多くのフローチャートアプリケーションがあります。 Balsamiq Mockups が役に立ちました。お役に立てば幸いです。
写真は何千もの言葉に値します。 Use CaseおよびSequence図。これらは、ソフトウェアの目的/フローを説明するのに十分なはずです。
PS：ソースにコメントを詰め込まないようにすることは何でも。それがバージョン管理システムに保存されている場合は特に、肥大化します。代わりに、推奨される図を参照するいくつかの番号/コードを追加してください。
https://stackoverflow.com/questions/152160/using-noweb-on-a-large-Java-project 以降、文芸的プログラミングとCOBOLまたはFORTRANへの移行を提案するか、単に理由を尋ねることもできます彼は、すべてのグラファイトがツールの使用方法をすべて説明する必要はありません。
あなたは専門家であり、ここでは緑がかったストロークをペイントし、2pxのガウスぼかしなどを適用することを詳しく説明するのではなく、ハイエンド製品を提供することが期待されています。