ハンズオンのjfluteレビュー

概要

DBFluteハンズオンで、jfluteレビューを受ける方へ

環境構築

Gitリポジトリの準備

レビューワー・レビューイー双方がコミット権限のあるgitを用意してください。

以下の二つが考えられます。

  • A. レビューイーのGithubアカウントでフォークしてレビューワーに権限を付与 (公開レビュー)
  • B. 別のgitリポジトリにハンズオンをコピー (そして双方に権限を付与) (公開・非公開はgit次第)

(組織的にレビュー運用している場合は、大抵は "B" の可能性が高いので周りに確認をしましょう。複数人でリポジトリを共有するのであれば、それぞれ自分用のブランチを作成しましょう)

以下がオフィシャルリポジトリです。フォークもしくはコピーする場合はこちらから:

GITリポジトリ
https://github.com/dbflute-session/dbflute-hands-on.git
プロジェクト
dbflute-hands-on

gitignoreの調整

レビューワーもローカルで同じように動作させたいです。オフィシャルのハンズオンプロジェクトはコミットすることを前提としていないので .gitignore を調整します。 (すでに調整済のプロジェクトを利用される方はこちら不要です。周りに確認してみましょう)

まず、プロジェクト直下の .gitignore から以下のように除外対象を削除します。

  • Eclipse欄の /.settings /.project の2つ
  • DBFlute欄の /dbflute_maihamadb /mydbflute の2つ
  • application欄の /pom.xml の1つ

加えて、以下の.gitignoreファイルをまるごと削除します。

  • src/main/java/org/docksidestage/handson/.gitignore
  • src/main/resources/.gitignore
  • src/main/resources/org/docksidestage/handson/.gitignore
  • src/test/java/org/docksidestage/handson/.gitignore

除外対象を削除するということは、それをコミット対象にしたいということです。 主に、EclipseやMavenの設定、DBFlute自体、自動生成や手動作成されるJavaのクラスなどをコミット対象にします。 一方で、コミット対象にしないものの代表としては、MySQLの本体が挙げられます。(OSに依存するものは各環境で用意すべきなのでコミットしない)

レビューのやり取り

レビューコメント追加 by レビューワー

レビューイーがコミットしたことをレビューワーに知らせると、レビューワーの方でFetch&Pullしてレビューします。そして、以下のようなレビューコメントを入れます。

e.g. レビューコメント追加 by レビューワー @Java
// TODO you これはこうです by jflute
...

確認して修正したらdone by レビューイー

レビューイーは時折 Fetch&Pull してレビューの有無を確認し、優先して修正してください。 そのとき、todoコメントは done と一言入れて残しておいてください。 (todo自体を消すとどんなレビューをしたかわからなくなるため、todoは残しておきます)

e.g. 確認して修正したらdone by レビューイー @Java
// TODO done you これはこうです by jflute
...

お知らせ・読み物課題コメント by レビューワー

お知らせや読み物課題と言った、コードアクションではないtodoもあります。この場合は読んで理解できたらdoneをしてください。

e.g. お知らせ・読み物課題コメント by レビューワー @Java
// TODO you [お知らせ]こうなんですよぅ by jflute
...
// TODO you [読み物課題]このURLのサイトを読んでおいてください by jflute
...

わからないところがあったらtodo by レビューイー

飛ばして先に進んだり、できたけど自信がないとか疑問に思うようなところは、自分用のtodoコメントを入れておきましょう。ただのコメントだと後で忘れてしまうものです。

e.g. わからないところがあったらtodo by レビューイー @Java
// TODO you うーむー、ここがこれこれこうでわからん。ので後で
...

セクション1での補完テンプレートを入れていれば、_todo => ctrl+space でtodoコメントを補完できますので、ぜひ使っていってください。

聞いてみたいことがあったらtodo by レビューイー

コード上のtodoコメントで質問してください。_trev => ctrl+space で相手を指定するtodoを補完できます。 技術的な話をリモートで質問するのもトレーニングの一つです。背景や論点などを整理してしっかり伝えることができるか?まあ、気負わずにやってみてください。

e.g. 聞いてみたいことがあったらtodo by レビューイー @Java
// TODO jflute これこれこうでわからんのですが、これってこれこれこういうこと? by you
...

似たようなところが他にもないか探す by レビューイー

todoをされた箇所だけじゃなく、それと同等のコードが他にもあったらそちらも直すようにしましょう。

実業務でも、バグが出て直してすぐに別のところで全く同じバグがあって直して...の繰り返しはしたくないものです。 ひとつ指摘されたら似たようなところが他にもないか探す という習慣が大切です。

レビュー待たずに先に進む by レビューイー

jfluteのレビューは、夜中や土日が中心でいつできるかわからないので、レビューを待たずに先に進みましょう。

ただ、あまり先に進み過ぎるとレビュー指摘による横断的な手戻りが発生しやすいので、最初の頃はレビューを催促してください。逆に、手戻りが発生しないように、レビューをもらったらレビュー修正を優先しましょう。

帰る前にはコミット&プッシュする by レビューイー

ハンズオンは気軽にコミットして問題ありません(コンパイルエラーや警告が残ってないようにだけ注意)。 バックアップも兼ねて、帰る前にはコミット&プッシュしましょう。夜中にjfluteがレビューするかもしれません。

コードポリシー

jfluteのレビューを受けるために、以下のことを意識お願いします。

コーディングテーマ

こちらのブログのとおりです。

エディター警告の解決

Eclipse や IntelliJ のエディター上の警告が残っている状態でコミットしないように気を付けましょう。 (自動チェックされるものをレビューするのは無駄なので)

現場によっては、checkstyleが効いていることもあるでしょう。checkstyleの警告が残らないようにしましょう。 警告をどう直したらいいのかわからないときは、todoコメントで質問をしてください。

最低限のJavaDoc

新しくクラスを作ったときは、クラスのJavaDocを付けて @author を付与します。(@au => ctrl+space で補完) もちろん、JavaDocらしい気の利いたコメントを書いてもOKです。(単に少なくともauthorだけは入れて欲しいというところです)

e.g. 最低限のJavaDoc, セクション2で最初のauthor @Java
/**
 * @author jflute
 */
public class HandsOn02Test extends UnitContainerTestCase {
    ...
}

ハンズオンではあまりありえない状況ですが、他の人が作ったクラスに (レビューコメント以外で) 手を入れる場合は、@author を下に追加します。

e.g. 最低限のJavaDoc, セクション2でauthorの追加 @Java
/**
 * @author jflute
 * @author stojkovic
 */
public class HandsOn02Test extends UnitContainerTestCase {
    ...
}

誰が修正をしたのかって別にgitのHistoryを見ればわかる話ではありますが、クラスファイルを開いたらすぐに目に入ってくるというのがポイントです。 特にインクリメンタルな開発の場合、とある人が途中まで作ったものを別の人が引き継いだりと複数の人が関わることが多く、緊急の場面でのコードリーディングも多いと想定されるので、すぐに「話しかけたい人」がわかるというのが大切だと考えています。 また、複数の人がクロスしてクラスを修正していると、ササッとその場限りで都合のよい無責任実装が積み上がっていきやすいものです。手を動かして記名することで少しでも「自分が関わったクラスなんだ」という意識を高めることも目的の一つです。

空行マネジメント

空行には「区切り」という明確な役割があります。

いい加減に空けたり詰めたりすると「見た目で理解しづらいコード」になってしまいます。 必ずこうしなければならないというルールがあるわけではありませんが、まずは統一性を大切に、そして、ぱっと見で読み手がコードの意図を汲み取りやすい空行を心がけましょう。

また、ディスプレイは横長のものが多く、縦が短いものです。無駄な空行は削除(Eclipseならctrl+D)していきましょう。ただ、もちろん意味のあるものはOKだし、空けるべきと思ったところは積極的に空けましょう。

e.g. 空行マネジメントされたデモコード @Java
/**
 * @author jflute
 */
public class HandsOn02Test extends UnitContainerTestCase {

    public void test_demo() throws Exception {
        // ## Arrange ##
        String prefix = "S";

        // ## Act ##
        List<Member> memberList = memberBhv.selectList(cb -> {
            cb.setupSelect_MemberStatus();
            cb.query().setMemberName_LikeSearch(prefix, op -> op.likePrefix());
            cb.query().existsPurchase(purchaseCB -> {
                purchaseCB.query().setPaymentCompleteFlg_Equal_True();
            });
            cb.query().addOrderBy_Birthdate_Desc();
        });

        // ## Assert ##
        assertHasAnyElement(memberList);
        memberList.forEach(member -> {
            String memberName = member.getMemberName();
            log(memberName);
            assertTrue(memberName.startsWith(prefix));
        });
    }
}