私の上司は、コードのナレーション付きの行ごとの英語の説明を望んでいます

私は、上司が読んでフォローできるようにしたい説明や解説を、1行ずつ（または必要に応じて、たとえば画像ごとなど）与えるように特に求められました。

彼はプログラマーではないので、彼はコードに従うことができないので、すべてを英語に翻訳したいと思っています。

これを行うように誰かに頼まれましたか？

すべてのソースコードについてコメントし、JSDocを使用して、すべての関数、変数などの完全なドキュメントを生成し、実装例と、コメント付きの完全に機能するデモを含めました。

プログラマでない人のためにコードにコメントするために私ができることは他にありますか？

これは合理的な要求ではありませんか？

更新

最後に、私は彼が求めていたことをするのに時間の良い使い方ではなかった理由をなんとか説明することができました。彼は理にかなった男であり、私の仕事が何を含んでいるかを理解していませんでした。彼がこの投稿を見たとき、彼はそれが通常のリクエストではないことをすぐに理解したと思います。

他のプログラマーが従うのに適したドキュメント（JSDocおよびインラインコメント-技術的な問題に関する追加のメモ）と、上司が従うプログラムのメインロジックの非常に広範なフローチャート図を提供しました。

最終的に、すべての関係者は満足し、私たちは前進しました。

いいえ、それは合理的な要求ではありません！

ITから彼の話、または他の誰かが、すべての手段によって、それから彼の話を持っています。それは非合理的な考えであり、実行可能であれば非常に高価ですが、実際に実行されるべきではありません。関数とサブルーチンの概要は合理的ですが、すべてのコード行を「説明」することはできません。彼がそれをするよりも、手にある言語を読むことを学ぶ方が効果的だろう。

彼が次に求めるのは、数式、またはその他を英語のテキストに翻訳することです。確かに可能ですが、それはエラーと誤解の余地をもたらします。コードを英語に「翻訳」するのと同じです。

あなたが持っていますか設計文書を？これらは、コードが行うことの英語による説明です。プログラミング以外のマネージャーは、それ以上を必要としません。

マイクロマネージャーオブザイヤー賞はありますか？あなたの上司がノミネートに値するようです。コードを行単位で理解する必要があるが、コードの直接的な読み方を学びたくないと考える人は、想像できる限りマイクロマネージャーと同じくらい完璧です。

開発者であることの利点の1つは、コードを理解するのが難しいため、少なくとも詳細な実装レベルで、少なくとも非技術的な管理によって、ある程度以上のマイクロ管理ができないことです。そのレベルで頭の上に。しかし、あなたの上司の天才は、シリコンカーテンを粉砕する方法を見つけたかもしれません。

そして、ボーナスとして、英語の翻訳を使用してさまざまな改善を提案する前に、開発者が翻訳を行うのに膨大な時間を浪費します（プログラマーよりも優れたコーディング方法を知っていると仮定しています）コードを読んで、誰かが翻訳するとすぐに彼の知恵を共有できるようになります。そうでなければ、なぜすべての行を翻訳する必要があるのでしょうか？）

だから、いいえ、それは合理的な要求ではなく、私はそれを聞いたことがありません。そして、私はあなたのために感じています。誰もが静かに別の仕事を探し始める必要があるかもしれないと思う。なぜなら、彼が管理ツールとしてコード翻訳を使い始めると、おそらく残酷な仕事の場になるだろうからだ。

プラス面として、あなたの状況にちなんで名付けられた新しいアンチパターンを手に入れることができますか？モンティパイソンのスキットの後、コミカルに誤訳されたハンガリー語のフレーズ集を使用して英語を話せない人とコミュニケーションを図ろうとする「Dirty Hungarian Phrasebook」アンチパターンはどうですか。

彼と一緒に座って、コードの10行を通して彼に話しかけます。あなたが両方とも彼が望む範囲でそれを理解することに同意するまで、すべての詳細を説明します。

たぶん、この経験は彼が探しているすべてです：あなたの仕事があなたにどのように見えるか、そしてあなたの観点からソフトウェアがどのように見えるかの印象だけです。それは私の本では良いことです。

この後、彼はまだあなたに続けてほしいと言ったら、言って下さい：私が尋ねなければならなかった質問の数に注意してください 質問をすることなくこのすべてを説明しなければならなかったとしたら、どうすれば何を含め、何を省けばよいのかを知ることができたでしょうか？結果があなたの役に立つようになるまでにどれくらい時間がかかりましたか？さて、このようにしていくつの行をやりたいですか？

私はそれが合理的な要求だとは思わない。ソースコードは、英語（または他の言語）で読むことを意図したものではありません。

たぶん、彼はあなたがあなたのコードに彼が承認しない、または気づいている何かをさせるだろうと恐れているのでしょう。もしそうなら、私はあなたがそれに対してできることはないと思います。ドキュメントを作成するか、コードを監査するために誰かを雇うように説得する必要があります。

本当に簡単です：

• あなたはプログラマとしてのスキルのために雇われました
• あなたのマネージャーはこれらのスキルを持っていません
• エルゴ、あなたのマネージャーはあなたが何をするかを完全に理解できると合理的に期待するべきではありません

私は以前の仕事でこれと同様の経験をしました。私のマネージャーは会計士であり（したがって、非常に低レベルの詳細志向）、プログラミングを理解していないか、本当に信頼していませんでした。彼女は、非技術者として、自分が書いたものの特徴を理解できると期待すべきでないことを理解できませんでした。過剰なドキュメントの要求や、技術者以外のユーザーにコードの管理と変更の方法のトレーニングを要求した後（はい）、私は彼女を盗もうとするのをやめ、完全に拒否しました。説明に使用した例えは簡単でした。

• 私は会計士ではありません
• 個々の取引やアカウントへの投稿をすべて理解することを期待すべきではありません
• これは、単にアカウントが理解できないという理由だけで、アカウントが間違っている、または信頼できないという意味ではありません
• これは、それらを編集した人を信頼することで可能になります

結局のところ、これは私にとってこれがどのように聞こえるかです。従業員を信頼するのが難しいマネージャー。または彼らが去ることを恐れ、これがそれを軽減する効果的な方法であると考えます。

これに対する唯一の解決策は、座って、なぜこれが意味をなさないのかを説明することです。あなたの仕事は、コードを理解し、あなたと同じスキルを持っている人があなたのマネージャーではなくそれを理解できるようにすることです。このスレッドを表示するのは良い考えかもしれません（または、性格によっては、本当にひどいものです）。

行ごとに、とんでもないです。私が提案できるのは、コメントからドキュメントを生成し、それを彼に提供することです。これは、私が過去に取り組んできた多くのカナダ政府の助成金と監査に十分でした。

彼はライン・バイ・ラインを取得することはありませんが、彼は法・バイ・メソッド必要があり得るでしょう、まだ彼が必要以上に細分することを。

プラットフォームに応じた既存のソリューション：

• C＃：サンドキャッスル
• Java：javadoc
• 「C ++、C、Java、Objective-C、Python、IDL（CorbaおよびMicrosoftフレーバー）、Fortran、VHDL、PHP、C＃、およびある程度D」：酸素

興味深いアプリケーションのコード全体を英語に翻訳するよりも、コードの読み方を学ぶ方がはるかに速くなります。その上、私たちはCOBOLでそれを試みましたが、まったく役に立ちませんでした。彼が学ぼうとしないが、彼の無知を他の誰かの問題にしたいだけなら、あなたは真剣に先の尖った上司を持っています。

技術的な専門知識を使用して、上司を追跡します。

1. 最初にコーディングするのと同じくらいの時間がかかることを彼に知らせてください（自由に長くしてください）。
2. このドキュメントを最新にする必要があるかどうか彼に尋ねてください。すべてのコーディングの変更に少なくとも2倍の時間がかかることを彼に知らせてください。
3. あなたや他の誰かがバグを見つけた場合は、今すぐ修正するか、または擬似コーディングが完了するまで待つかどうかを彼に尋ねてください。＃1と＃2について思い出させます。

すべての悪い解決策の提案と同様に、問題を特定することをお勧めします。上司が経営陣による技術的な質問にぶつかって、答えられないので恥ずかしいと思うかもしれません。彼が最も心配していると感じるコードの特定のセクションが1つある可能性があるため、この大規模な取り組みをその領域だけに制限することができます。

サンプルを提出することで、コーディングの仕組みを理解していない場合（ループとは何か、これらすべての項目に対して何をしているのか）、どの言語であるかは重要ではないという結論に達するかもしれません。パワーユーザーの観点からアプリケーションを理解すること。あなたが本当のコード/ヒントを書くことを望んでいることを彼に知らせるのは公平だと思います-私は別の仕事を探しています。

どうして？

行ごとの解説は合理的ではありませんが、ここに私が尋ねるものがあります：なぜあなたはこれが欲しいのですか？

なぜなら…

• あなたはソフトウェアが何をするのかを完全に理解したい（必ずしもどのようにではない）？
• あなたが私が去った場合、別のプログラマーがプロジェクトを選択できることを確認したいですか？
• あなたは私が本当の仕事をしているのを見たいですか？

この要求の背後には合理的な願望があるかもしれませんし、それを理解し、そのニーズを満たすことで上司を幸せにすることができるかもしれません。

更新

Mikey'sコメントに基づいて、多分私はこれを少し率直に言ったかもしれません。私はあなたが文字通り「なぜあなたはこれが欲しいのか？」と言うべきではない、ただあなたがそれを見つけるべきであるということです。言葉遣いと声のトーンは大きな違いを生みます。具体的には、次のように言うことができます。

「私は、コードのすべての行について説明したいというあなたの要求を考えてきました。そのようにするのは少し珍しいことです。自分の仕事についてうまく伝えていないことがあるのではないかと思っていました。私たちのコードについて、または私がやっていることについて本当に理解したいことは何ですか？ここで何を達成しようとしていますか？」

もちろん、上司がまったく無理である可能性があります。しかし、この要求がどれほど風変わりであるかを知らず、合理的な目標を念頭に置いている可能性が高くなります。

そうでない場合は、履歴書の研磨を開始します。:)

リテラシープログラミングを試す良い機会のように思えます。Google it。:)

しかし...それは必ずしも完全に不合理な要求ではありません。あなたの仕事の一部（より重要な部分、imo）は、アルゴリズムを他の開発者、そして必要に応じて非技術者に伝えることです。コミュニケーションできない孤独な天才プログラマーは、常に問題があると思います。

そのためには、コードを非常に明確にする必要があります（つまり、真の自己文書化または適切な文書化のいずれかです。「自己文書化」とは、変数と関数が1つの意味または責任を持ち、その名前が明確に反映していることを意味します）。あなたの上司は、彼の要求に正当な理由があるかもしれません。たぶん（私はここで推測しています）あなたまたはあなたの前任者は、突き通せない、もろいコードに対して評判があり、これはあなたの上司の救済策です。それは少し極端ですが、あなたにとって役に立つ練習になるかもしれません。彼は、より良いドキュメントを書くには時間がかかることを知っていると思います（もしそうでなければ、彼は教育を受ける必要があります。まるで用語論文を書くようなものです。読むよりも書くのに時間がかかります）。

行ごとの翻訳でさえ、コードの各行の意味を効果的に伝えません。コードの行を理解するプログラマーは、常に多くの要因のコンテキストにあります。マルチスレッドコードの一部のようなものに入ると、英語の翻訳は生のコードよりも意味がありません。複数の機能/ファイルにまたがる機能について考えてください。他のコードを大量に説明しなければ、一部のコードはまったく意味をなしません。依存性注入に関係するさまざまな部分を「行ごとに」説明しようとすると、私が何を意味するかがわかります。神関数の手続き型コードを超えるものはすべて、英語の翻訳を理解するためだけに膨大なプログラミング知識を必要とします。また、if / else決定ステートメントのような単純なものを見てください。行ごとではなく、次の行は実行時データに依存しているためです。次の行は、いくつかの可能性の1つです。アプリケーションが何をするかを説明するまでに、PMをプログラマーにして、2人とも5歳になります。

私はプログラミングを教えていたので、私はそれを試して満足しているだけです。

彼はすぐに私がいるので、彼は私を悲しくさせるであろう、彼はのために予想以上になってきて見つけるだろうが好きなものを説明する:-)

あなたの「ボス」に言及するとき、これは「あなた/あなたのチームを担当する中間管理者」ですか？またはあなたの会社の所有者？「時間単位で」支払われますか、それとも「給与」で支払われますか？

上司が説明責任のある中間層マネージャーである場合は、ボスと話してください。上司の要件を満たすために、会社に対する生産性は、現在の3分の1に削減されると指摘します。

あなたの上司が「小切手に署名する人」であれば、同じことを外交的に説明します。あなたの仕事は「コードを書く」から「コードを書く、コードの説明を書く、説明を説明する」に行きました。

フローチャートはおそらく彼にとってより有益でしょう。これは確かに珍しい要求であり、マネージャーとしての彼についてはあまり語っていません。

あなたの上司があなたが書いたコードを理解するのにいくらかの時間を費やすことをいとわないという事実は、あなたの利益のために使うことができます。彼をCucumberに紹介してみてください：http : //cukes.info/

将来的には上司にBDDテストを作成してもらいます。

彼はそのことを気にしないでください。ソフトウェア開発の実装は変更される可能性があることを彼に伝えてください。イベントのデザインは変更される場合があります。情報の隠蔽、カプセル化、抽象化について彼に話してください。
彼は、あなたのチームの一員として、あなたのコードのクライアントとして、より広い意味で、あなたのコードが行うことの明確で高レベルの抽象化でのみ動作するべきです。コードの任意の層が他の誰かのコードの別の層と同じように機能します。それ以上のことを知っていても、彼は遅くなり、コードの内部動作に基づいて仮定を立てるリスクがあります。あなたがコードを変更しなければならないとき、彼がそれらに基づいて何らかの種類のシステムまたはプロセスを構築した場合、これらの仮定は問題になります。
また、この種の作業を行うと、効率が低下します。2つの異なる場所で後続の変更を行う必要があるだけでなく、仕事の士気にも悪影響を及ぼし、出力がさらに低下します。

英語の美しさは、美しく難読化されていることです。これをあなたの利益のために使うなら、あなたは二度とこの種の要求に対処することを強要しないかもしれません。サンプルとしてコードの小さな断片を取り上げますが、非常に抽象化されており、理解しやすいものではありません。それから、あたかもプログラミングの本の章のためにコメントを書いているかのように、技術的な英語でコメントを書きます。長く複雑であるほど、より良い結果が得られます。この1つの機能を文書化するのに何時間かかったかを彼に伝えてください。次に、実際のコードベースの1％の1/10（可能であれば、コード行に基づいた実際の数値を使用してください。おそらくこれよりも悪い）であることを説明します。彼は、英語の翻訳が何を言っているのかわからず、このレベルのドキュメンテーションを行うのに20,000人時を要すると気づいたとき、彼はかなり迅速に後戻りします。しかし、彼の仕事を達成するために非常に真剣に試みてください。ドン;あなたがそれをやってのけることができず、彼があなたが彼をプレイしている疑いがあるなら、これを試さないでください。

これは、特別な休日発行の先のとがった髪のボスのディルバートストリップの候補のようです！彼の要求は確かにしない音一見合理的。

ユーモアはさておき、彼が本当に必要なものとその理由を見つけて、それを彼に与えるのに何ドルまたは何時間かかるかを彼に助言し、彼がそれに多くのお金を使いたいかどうかを彼に決めさせます。

あなた自身に関しては、彼が一見奇妙に見える要求に応えるのにかかる時間を数え、その時間の一部を投資してあなたを喜んで雇う雇用者のために働く新しい仕事を見つけた方が良いかどうかを判断しますプロとして！

彼をあなたのオフィスに連れて来て、彼にあなたのコードのツアーを与えてください。

彼は、彼が不条理な要求をしたことを途中で実感するでしょう、そして、彼は立ち去り、あなたを二度と煩わせません。

あなたが彼があなたのコードを理解しようとするのを手伝うという彼の要求に屈しないなら、彼はあなたを突くための異なっているが等しく不条理な方法を見つけるでしょう。

これは、なだめるよりもなだめる方がうまくいく場合です。

これを行う翻訳者「Language X to English」があればとてもいいです。それから人は笑って、問題ない、ボス、あなたはそれをすぐに持っているでしょう。次に、数メガバイトのテキストを含むメールが届きます。

• aを20個の要素を持つ新しい整数配列とします。
• xを整数を格納する変数とします。
• xを0に設定
• xが20より小さい間、次の2行で規定されていることを行います
• インデックスxを持つaの配​​列要素を、引数x + 1でnThPrimeを呼び出した結果に設定します
• xを1増やす
• ....

別のオプションは、今後シェークスピアでのプログラミングを提案することです。

私の上司は、コードのナレーション付きの行ごとの英語の説明を望んでいます

タフ。

彼はプログラマーではないので、彼はコードに従うことができないので、すべてを英語に翻訳したいと考えています。

彼がプログラマーでない場合、彼はコードを読んではいけません。まったく。

代わりに高レベルのドキュメントを提供してください。

これは合理的な要求ではありませんか？

番号。

プログラマーとして、あなたには本当に「2つの」仕事があります。

1つは、優れたプログラムを作成することです。2つ目は、社内外の顧客に「販売」することです。

あなたの上司の要求はあなたの最初の仕事を「傷つけます」。プログラムを文書化するのにより時間がかかります。他方、彼は実際にあなたをあなたの「第二の」仕事でもっと一生懸命働かせています。

あなたの上司は、あなたのプログラムを英語で文書化して、HISの利益のために、おそらく彼が社内外で対処しなければならない人々の利益のために文書化するよう求めています。彼が彼の仕事をするのを手伝うならば、あなたがより多くのハードウェア、人員、または昇給のためのお金を彼に頼むとき、それはあなたの利益のために働くでしょう。結局のところ、彼はあなたにもっと仕事をするように頼みました。

BDDはこの問題に適していると思いますが、プロジェクトは完成に近づいているように見えますので、現在実装するのはちょっと難しいので、今後の参考になります。

BDDでは、ユースケースは人間が読み取れるドキュメントとして記述され、自動化された機能テストに変換されます。

おそらく、このリクエストはANTLRのようなことを学ぶ良い機会です。ANTLRを取り、あなたの言語の文法を取る、あなたが持っているすべてのコードを解析し、あなたのトラバースASTのすべてのノードに対して生成テンプレートベースの記述を、そのi++ように説明されますincrease i by 1 using postfix increment operator。それは本当に面白いはずです。上司は、このツールをビルドスクリプトに含めることを希望する場合もあるため、変更を加えるたびに、新しいバージョンの機能を説明する〜20 MBの電子メールを受け取ります。

PS冗談です、彼はバカです。

私は、これは不合理要求であることに同意しますが、あなたの上司は、の出力のようなもの理解し得るDocco 1を上のコードで、あなたのコードおよびライン・バイ・ラインまたは2列のHTML出力への句ごとの句のコメントを分離し、側と散文の他。もちろん、自分でコメントを入力する必要がありますが、プレゼンテーションは技術に詳しくない読者にとっても、かなり見栄えが良いです。たとえば、Underscore.jsの注釈付きコードの行ごとのコメントセクションを参照してください。Pythonおよびシェルスクリプトバージョンもあります。

あなたの上司が単に知らされておらず、脅迫されている可能性がありますが、実際には合理的な人です。もしそうなら、彼/彼女との推論はうまくいくかもしれません-あなたが「彼が本当に欲しいもの」を提供することを約束するカジュアルな会話。プログラムが何をしているかについての散文ガイド。

それが「私の道か高速道路」に下がったら、今すぐあなたのガソリンをチェックしてください。

cucumberなどの動作駆動設計フレームワークを使用して、いくつかの受け入れテストを作成できますか？それはコードを説明しません。それが何をするのかを自然言語で説明します。また、実行可能という利点もあるため、ドキュメントが最新であることを常に確認できます。最新でない場合は、テストランナーが赤くなります。

紹介ビデオをご覧ください。たぶん、新しいボスを見つけている間、それは良い転換です... ;-)

あなたのマネージャーは、彼が管理していることを人々が何をするのか理解していないという事実にほとんど間違いなく悩み、彼らが生み出す結果を理解する背景を持っていません。

私は彼がこの解決策を非常に徹底的に考えたのではないかと疑っています。おそらく一見しただけで理にかなっているように思われます。しかし、それは主に、プログラミングコードが実際に何であるかを彼が理解していないためです。

プログラマーなら誰でもこのリクエストの不条理を理解していますが、私たちが理解できるのは、いったん言語を通過すると、明らかになるのはアルゴリズムであり、同様に不可解であるためです。

// 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時間しかかかりません。彼は、ほぼ確実に数日後にあきらめますが、少なくとも彼は何を伝えているのか、そしてもっと重要なことには彼があなたのコードを読みたくない理由を知っているでしょう。

私見...彼が仕事を成し遂げる責任があるなら、彼はそれがどのように機能するかを知る必要があります... :)