馴染みのないコードベースで作業する方法

私たちの職業では、なじみのないコードベースに取り組むのが一般的です。新しいプロジェクトに参加するたびに、あるいは大きなプロジェクトでこれまで手つかずだった部分に取り組む必要があるたびに、このようなことが起こります。

この問題は、開発者がバグを修正する必要があることに限定されません。それは、新しい機能を設計しなければならないソリューション アーキテクトである場合もあれば、空き時間に GitHub の問題に取り組んでいるオープンソース コントリビューターである場合もあります。したがって、他の人に利益をもたらすために、私がこの状況にどのようにアプローチするかを説明したいと思います。

問題の例

私の要点を説明するために、オープンソース プロジェクトの新機能をリクエストする一般的な GitHub の問題を使用します。

Hazelcast で働いている間、私はハッカソンで取り組むために、いわゆる「最初に良い問題」を定期的に調べていました。私にはそのようなハッカソンを実行することはできませんでしたが、それは問題ではありません。私のアイデアは、オープンソースへの貢献に興味のある人々がコード ベースに慣れ始めるのを助けることでした。

そのとき、次のような興味深い問題を見つけました。

getQuiet 操作のサポートを追加しますhttp://ehcache.org/apidocs/net/sf/ehcache/Cache.html#getQuiet(java.lang.Object) ?

アイデアは、エントリに触れずにエントリを取得できるようにすることです。つまり、最終アクセスのタイムスタンプは更新されません。

その背後にある使用例は、キーの削除を変更せずにキーの存在を監視できるようにすることです。

--分散マップ: getQuiet 操作のサポートを追加

オープンソースの貢献者として、仕事にどのようにアプローチすればよいでしょうか?

図解が鍵

ドキュメントの作成は、新しいプロジェクトに着手するための最初のステップです。通常のプロジェクトでは、ドキュメントが欠落しているか、不完全であるか、または部分的に (完全ではないにしても) 誤解を招く可能性があります。ハッカソンでは、時間が短すぎて詳細を読むことができない場合があります。

成功したオープンソース プロジェクトには、一般的に優れたドキュメントが用意されています。ただし、ドキュメントは主にユーザーを対象としており、開発者を対象とすることはほとんどありません。たとえそのような場合でも、ドキュメントで問題が解決される可能性は低いです。

このため、私の入り口は図を描くことです。一部のツールではコードをリバース エンジニアリングして図を自動的に描画できますが、私はそれらを意図的に使用していないことに注意してください。図を手動で描画することには、自動生成される図に比べて多くの利点があります。

• ここでは、当面の問題に関連するコードの領域に焦点を当てます。

• これにより、引き出し者は、唯一の真実の情報源であるコードを読んで理解することが強制されます。

• それはコードのメンタルモデルを構築します。

• 後でアクセスできるように、調査結果を文書化します。ただし、基礎となるコードが進化し、両方が途中で終了するにつれて、ドキュメントの価値は時間の経過とともに減少することに注意してください。

問題のコードの図を作成してみましょう。まず、リポジトリをローカルにクローンして、お気に入りの IDE で開きます。唯一必要な機能は、メソッド呼び出しをクリックすると、そのメソッドにリダイレクトされることです。

図そのものについては、時代遅れだと言われても仕方がありませんが、私は次の 2 つの理由から、今でもUML シーケンス図を好みます。

• 私には彼らとの経験があります。

• セマンティクスはその場限りのものではなく、UML をある程度知っている人々の間で共有されます。

早速、以下のとおりです。

図を描くと、問題がどこにあるのかをすぐに特定できます。

 public abstract class AbstractCacheRecordStore<R extends CacheRecord, CRM extends SampleableCacheRecordMap<Data, R>> implements ICacheRecordStore, EvictionListener<Data, R> { protected long onRecordAccess(Data key, R record, ExpiryPolicy expiryPolicy, long now) { record.setAccessTime(now); // 1 record.incrementAccessHit(); return updateAccessDuration(key, record, expiryPolicy, now); } //... }

1. DefaultRecordStoreはRecordを読み取り、最終アクセス時刻の更新をトリガーします。

問題の修正はこの投稿の範囲外です。最適なソリューションを開発するために、全体的な設計に精通している人々と話し合うことが含まれます。ハッカソンにおける良いアプローチは、まず少なくとも 2 つの代替案を提示し、それぞれのトレードオフを文書化することです。

ツールに関しては、多くの代替手段が利用可能です。私の好みはPlantUMLです。

• WebアプリとDockerコンテナを提供します
• SVG または PNG 画像を生成します
• スキン可能です
• オープンソースで無料です
• 定期的にメンテナンスされています

結論

既存のコードベースを理解することは、その人の正確な技術的役割に関係なく、重要なスキルです。図を作成することは、この目標に向けて大いに役立ちますが、文書化というさらなる利点も得られます。

私は UML 図が好きです。なぜなら、UML 図は馴染みがあり、共通のセマンティクスを提供するからです。

したがって、コードベースをより深く理解したい場合は、単にコードを読むだけでは不十分です。図を描く必要があります。

初出は 2023 年 5 月 14 日にA Java Geekで公開されました