他の開発者にコードを説明する上でどうすればよいですか？[閉まっている]

質問自体はばかげているように聞こえるかもしれませんが、問題が私の仕事のパフォーマンスに悪影響を及ぼしていると感じているので、答えは私にとって非常に重要です。

ここで少し背景を説明します。私は、ソフトウェア以外の会社の中規模ソフトウェア部門の経験豊富な上級ソフトウェア開発者です。物事の技術的な面では平均を上回っていますが、私は物事を伝えたり説明したりするのが非常に苦手です。他の開発者に何かを説明するときでも。

最も難しいのは、特定の小さなコードがどのように機能するかを説明するときに発生します。

面白いのは、たとえば、個別のモジュールとサブシステム間の相互作用など、何かがはるかに高いレベルでどのように機能するかについての例を説明および提供する方がはるかに簡単だということです。

より明確にするために、私が「ソースコード説明スキル」と呼ぶのは、

a）コードの実行フローを明確に説明する機能-たとえば、「これはそのThingを呼び出し、そのオブジェクトを返します。これは後でメソッドAを呼び出し、オブジェクトBを...に渡します」

a）現在の設計の問題を明確に説明する能力、またはより重要なのは、「パフォーマンス上の理由から、オブジェクトをクラスのフィールドとしてキャッシュし始めた場合、キャッシュが常に最新の状態になるように、10か所の場所で変更を加える」など

なぜ私が物事を説明するのが苦手で、説明を見つけられなかったのかを分析しようとしましたが、箇条書きで説明しているのかもしれません。また、私が説明しているとき、私は自分の発言や質問を見落としていること、人々の質問に集中しすぎているかもしれませんが、これらの質問はしばしば無関係であり、単に会話を引っ張ってしまいます。

何をすればいいのでしょうか（おそらく、間違いを何度も何度も練習すると思うので、実際には購入しませんが、「完璧にするための実践」を除いて）、私はソースを改善できます。スキルを説明するコード。

問題の1つは、小さなコードが常に全体像を説明するとは限らないことです。たとえば、慣れ親しんだプログラミング言語で不慣れなソースコードを見ると、通常、個々のステートメントのほとんどが理解できます。同時に、それらが貢献するなじみのないアルゴリズム、そのアルゴリズムが完全なソリューションで果たす役割、およびそのアルゴリズムが他の選択肢よりも選ばれた理由を理解するのに苦労するかもしれません。ある意味、私はそれらの言葉を理解していますが、まったく理解していません。

この例は、古典的な高速逆平方根関数です。

これを処理するのに役立つと思ういくつかのこと：

• ユーザーが使用するのと同じ言語でコードを説明します。
• 標準のプログラマ用語を使用してコードを説明します。たとえば、「バッファ」、「リスト」、「シングルトン」などの用語は、一般的な数学用語と同じように、ほとんどの人によく知られています。
• 入力と出力の観点から何をしているのかを説明してください。
• 言葉のない概念のための言葉を発明する。「アジャスター」、「チェーン」、「ラングラー」などの単語を、非常に節のある概念の省略形として使用することがあります。つまり、結局のところ、そもそもよく知られている用語が発明されたのです。
• 数行のコード自体は単純に見えるかもしれませんが、より大きなコードベースにおけるそれらの役割は非常に複雑になる可能性があることを認識してください。多くの背景情報を提供せずにそれらを常に説明することはできません。その場合は、提供してください。
• 具体例を挙げてください。
• 図を描く。

理由は簡単です。あなたはプログラマーのように思います。

概念を高いレベルで説明できることは、アイデアを伝えたいときに私たちが一生行うことです。ただし、プログラムを作成するときは、多くの小さく詳細な手順でタスクを実行する方法を理解する必要があるという考え方に身を置きます。それを説明することは、「小さな詳細なステップ」を誰もが理解できるものに変換する必要があることを意味します。これは小さな順序ではありません。そのようなことが簡単に理解できれば、誰でもプログラムできます。それこそがプログラマーです。

ただし、おそらくご想像のとおり、タスクを実行する方法を多くの小さく詳細な手順で理解することは1つであり、それらを適切に説明することはまったく別です。

私も、この取り組みにいくらか苦労しましたが、いくつかのトリックが私を助けていることに気づきました。あなたが作成したメソッドがあり、それがどのように機能するかを説明する必要があると仮定します。

• 最初の行から始める前に、メソッドを読んで、スコープが何であるか、どのような目的で使用されているか、いつ呼び出されたか、なぜこれを行うことにしたのかを思い出してください。要するに、それが何をするかを知っています。このようにして、メソッドの意味を包括的に含む方法で質問に答えることができます（つまり、「この行の要点がわからない」と言われたとき）、「これがインスタンス化するものです「接続文字列を使用して接続を確立するJDBCを呼び出す」ではなく、プログラム全体で使用されるデータベースへの接続。これは質問に答えますが、おそらくそれを明確にするものではありません）。
• メソッドの各行について、メソッドの全体的な目的にどのように寄与するかについて説明します。なぜそこにその行を置いたのですか？そうですね、この行は、レンダーループでアクションを委任する必要があるかどうかを確認するために、入力管理を担当するクラスを呼び出します。
• あなたのコードがおそらく不明確であるか、または改善される可能性があるときに認めます。不明確かもしれないコードを見つけた場合、それをより明確にするために書き直してください。同僚のプログラマーが見ているものを理解するべきだと考えるようにイライラさせるコミュニケーションには役立ちません。

一般的に、そのコードを何をするのではなく、なぜそこに置くのかに焦点を当てると、説明がより簡単に流れ、理解しやすくなります。

また、コードの実行フローの説明が低レベルで説明されるのに苦労することもあります。私を助けたのは、問題のプログラミング言語ガイド（C ++でのBjarne Stroustrupsプログラミング）を入手して、長年にわたって必然的に衰退してきた用語について自分をリフレッシュすることでした。さらに、新しい言語に関連する記事/ブログを読んで、最新の技術/用語を最新の状態に保ちます。

複雑な設計の問題/影響について：すぐに答えることなく、「より多くの分析を行わずに答えることはできない」と言っても問題ありません。ソフトウェアは非常に複雑になる可能性があり、最も賢い開発者でさえ、常にすべてのやり取りを頭に留めておくことはできません。

時間をかけてコードを分析し、答えをより確実にすることができます。それは確かに、即時の、おそらく誤った情報と間違った答えを与えるよりも良いでしょう。上級開発者の立場からは、それは賢明であると見なされ、応答性はあるが潜在的にばかげているように見えるのではなく、好意的になります。