同僚にコードを導入する方法

チームの新しいメンバーに、かなり複雑で多くの「落とし穴」が絡み合っているかもしれないコードベースをどのように紹介しますか？

最も簡単な方法は、全体的なアーキテクチャを図でレイアウトし、新しい人がコードに慣れるにつれて、明確に定義された（そして十分にスコープが定められた）タスクを数週間（または数か月）かけることだと思います。

しかし、コンサルタントとして（そしてその時点で下級従業員として）私は、時間の制約またはチームの役割の指定のために、それを常に持つことはできません。（私はこの特定のプロジェクトに他の誰かの2倍の長さで参加しているので、「ジュニア」は「コード/プロジェクトについてあまり知らない」という意味ではありません。）

私はプロジェクトとコードに新しいメンバーを紹介するように何度も任されましたが、悲しいことに毎回私は以前のものよりもそれほど良くないことがわかりました。私は図や写真が大好きですが、システムの複雑さを十分に説明していないと感じることがよくあります。（すべての小さなものの「落とし穴」はどうですか？）

このプロジェクトは、クライアントに引き継ぐところまで来ており、物事をより困難にするために、私が知識移転を行う人は、基本的に大学を卒業したばかりです。（上級開発者と知識の移転をするときのほうがずっといいというわけではありません。）

私はユーザーグループに月に一度参加し、その他の機会が生じたときに新しいトピックを紹介されることはありませんが、効果的な知識の共有を複製する能力は非常に不十分だと感じています。

どんなアドバイスも大歓迎です。私は主に私が従うことができるガイドラインを探しています。例：どこから始めますか？どのように進めますか？聞き慣れない技術やパターンを、一日中取らずにどのようにカバーしますか？どこでビジネスロジックとコード構造を結び付けますか？

ありがとうございました！

（いつものように、あなたが適切だと思うように質問を自由に編集してください。）

もちろん、ステップ1はコードから「落とし穴」を取り除くことです。明確で簡潔で一貫性のあるコードは、簡単に入手、操作、およびデバッグできます。

どこから始めますか？

私は新人に、彼らがどのようにコードベースに入りたいのか尋ねます。誰もが異なる学習をします。作業するタスクがほとんどない人もいます。既存のコードのデバッグが好きな人もいます。実行中のコードを見て、それが何をするのかを理解したい人もいます。エントリポイントから始めて、ただナビゲートしたい人もいます。一部のユーザーはvisioダイアグラムを必要とします...誰にとっても最適な設定パターンはありません。

聞き慣れない技術やパターンを、一日中取らずにどのようにカバーしますか？

私はそれらを避けます。新人がそれらについて尋ねるまで、それらをブラックボックスにしてください。それから、自分の時間でより多くを学ぶことができるか、一般的なものがよりよく知られているときに後で尋ねることができるというヒントで、それの要点を得るためにちょうど十分な情報を提供します。

どこでビジネスロジックとコード構造を結び付けますか？

しないようにしています。ほとんどの場合、新参者が自分で学習する方が、自分の考え方に合った自然な構造で頭の中に収まる方が良いでしょう。

覚えておくべきことの1つは、指示を短くすることです。人々はかなり早くチェックアウトする傾向があるため、その時点でそれ以上の指示は「固執」しません。15〜60分間物事を見せ（人によって注意時間は異なります）、5〜30分間休憩して処理します。

私の経験では、アーキテクチャ図が提供する広範な概要と実際にコードを操作することのざらざらした詳細との間のギャップを埋める良い方法は、システムのドリルダウンを行うことです。 ）またはユーザーが入力を行い（クライアントコードの場合）、次に関与するコードのすべてのレイヤーをステップごとに説明します。

別の方法は、ソースコードの「ガイド付きツアー」です。つまり、packages / namespaces / modules / directoriesを調べて、それぞれのコードが一般的に行うことを説明します。もちろん、これにはコードをある程度論理的にレイアウトする必要があります。

あなたは彼らにコードベースを教えているのではなく、彼らにあなたの仕事を教えているのです。彼らが必要とするかもしれないものを考えようとしないでください、あなたが仕事をするときに知るためにあなたが実際に必要としているものを見てください。

過去数か月のバグトラッカー履歴、スクラムユーザーストーリー、ステータスレポート、ソース管理コミットを取得します。どのファイルに最も触れましたか？最も問題のあるコードは何ですか？どのタスクが最も時間がかかりましたか？おそらく、ここ数か月間触れていないのであれば、あなたが思っているほど重要ではないでしょう。

机の上の印刷物を見てください。最近のブラウザ履歴を確認してください。頻繁に参照する保存済みメール、使用する連絡先、ダウンロードしたドキュメントを探します。私が他の人に伝えた最も有用な参考文献のいくつかは、最初にシステムを学習または設計するときに自分のために保管したメモです。どの参考資料が最も役立ちますか？

次に、既知のバックログをプルアップします。これらのタスクを完了するには、どのようなものを調査する必要がありますか？問題を含む可能性が高いコードの領域はどれですか？自分でメモを取っているかのように、その情報を伝えます。

毎日の仕事で図表を参照する場合は、それらを含めます。一度も作成したことがなければ、後継者や同僚にとってもそれほど有用ではないでしょう。

教えるときの最も困難なタスクの1つは、自分を靴にしようとすることです。この場合、あなたは彼らの靴の中にいます。ほとんどをつくる。

サポート作業が最善であり、簡単なバグを見つけて、それが見つかる領域を調べてください。コードがどのように適合するかをすぐに学習します。当然、彼らはこのバグとコードベースについての質問をするためにやって来ますが、彼らはそこに行きます（そしてバグを修正します）。多くの場合、例で物事を理解するのがはるかに簡単で、同様に、デバッガーでコードベースを実行することでコードベースを簡単に解決できます。

コードの変更が不明な場合（または、通常、コードベースに精通するまで、コードの修正が不確かな場合）、チェックインする前に確認できます。

もちろん、広範な概要とブロック図の既存のアイデアは、不可欠な最初のステップです。