coding-rules.md

AIESEC JAPAN コーディングの心構え

author @yuki-k-lion

概要

コードを書く上で守って欲しいこと、意識して欲しいことを書きます。 その時々の状況によりメンテナンスしてください。 背景とかは下の方に書いてあります。

coding rules

規約ではなく、心構えです。

レビュアーは これが守られていなくても、レビュー時に｢次から守ってね｣でapproveしてもいい。 その後別で修正するissue立てるようにしましょう。

初心者が初心者が練習用でこのコード触るので、厳密に規約を決めてしまうとマージできなくなってしまう。 できる人はlintなどを活用して後でリファクタしましょう。

大前提 レビューしやすいコード、読みやすいコードを心がける

• 余計な空行がない
• フォーマットがされている
• コードの背景がわかる。 わかりにくいならコメントを残す
• 変数名は省略しない。わかりやすい変数名を書く。（汎用的な名前をつけない）
• 一度にいろいろやらない...etc

やらないこと

データ構造が複雑で見えにくいもの

データ構造が複雑で、意識しなければいけないこと、理解しなければいけないことが多いもの。 データの戻り値やmapの中での処理など、実装者がデータの流れを誤って認識し、返り値が期待と異なるものになってしまう可能性がある。

ex map、stream など

const reformattedArray = kvArray.map(obj => {
  let rObj = {}
  rObj[obj.key] = obj.value
  return rObj
})

引用 Array.prototype.map()

今回の要件では、mapを使うほど複雑な要件はないと思われる. 基本forEachでできるはず。 mapを使用する場合はコメントを残しましょう。 テストもしっかり書きましょう。

mapを使用したい例としてはこんな感じ （いいコードではないです）

const pressPost = posts
  .map(post => {
    return !post.isPrivate ?? null;
  })
  .filter(post => {
    post.category = ArticleCategory.PRESS
  })

使いこなすには難しい概念を理解しなければいけないもの

• 厳密なatomic design（Pagesとtemplateを分けるなど）
• 厳密なDDD
• 厳密なTDD

これらの概念は、開発の効率化などの観点でとても有益ではありますが、 使いこなすには一定の訓練が必要です。

今回は開発経験がない人がメンテナンスしていくことを想定しているため、 訓練を積まなければ使いこなせない概念は使用しません。

vue/nuxt の思想から大きくぶれるオレオレ実装。

• 公式のドキュメントを読んでもわからず、一般的なコード規約からも大きく外れている。

一般的な記法から大きく離れる書き方は、読み手にとってはとても読みにくいです。 人間に優しいコードを書きましょう。

その塩梅がわからなければ、半年後自分がなんでこのコードを書いたか忘れてしまった時、もう一度見直してすぐに理解できるか、 という観点で考えてみてください。

使用した意図がわからず、読み解くのが難解なコード

• 対処療法的なバグ回避のためのコード etc

バグが発生する書き方をした場合、そのバグを一時的に回避するために入れる書き方は、 意図がわからず、拡張する時にデグレが発生する可能性があります。

もし、どうしても根本解決ができない場合は必ずコメントを残しましょう。

やること。（許容して欲しいこと）

共通化できるものはなるべく共通化し、変更の際のコストを下げる（責務を意識）

• 同じ責務を持つコードを複数書かない。DRY原則。

同じことをしているコードを複数箇所に書かず、なるべくまとめてください。

もし同箇所を修正する場合、同じことをしているのに複数箇所を修正する必要があり、 修正漏れ等が発生しやすくなり、バグを生む可能性が高くなります。

同じものを直すなら、一箇所修正すればいい。という状態にして欲しいです。

※厳密にやるのは厳しいので、なるべくでいいです。

意図がわかるコードを書く。難しい場合はコメントを残す。

自分にとって書きやすいコードではなく、後から知らない人が読んだ時に読みやすいコードを書きましょう。

何かを実装したり、拡張したりする時に、もっとも多くの時間を使うのはコードを書く時間ではなく、コードを読む時間です。
特にこのプロジェクトはあまりスキルが高くない人がメンテナンスしていくので、読みにくいコードばかりでは効率が落ちバグを産みます。

使い方が簡単で開発の生産性を上げるもの。中身を理解しなくても問題ない。

テストを容易にするためのツールで、中身を理解していなくてもよく、簡単にかけるものや、 コンパイルエラー等でレビューコストを下げてくれるもの。

• storyBook
• lint
• formatter
• etc

これらは初期の設定を入れるところは考慮しなければいけないことが多いですが、実際に使う人は考えることは少ないはずです。

特に初心者がメンテナンスするならば、自動的にコードの品質を担保してくれるツールは積極的に活用するべきだと考えます。
プログラミング初級者はどんな書き方がだめで、どんな書き方が良いのかはなかなか判断がつかないこともあるかと思いますが、
これらのツールがいい書き方を判別して教えてくれます。

Vue/Nuxtの公式ドキュメントに記載されている例とほぼ同じ形式で書いている、ドキュメントを読めば理解できるもの

• vue/nuxt custom html ( ex nuxt-link, v-bind , @onClick)
• plugin
• computed
• method ... etc

vue/nuxt が用意してくれている便利機能は使いたいです。 これらを更に複雑に応用するとなかなか初級者には厳しいところはあるので避けるのが良いと思いますが ドキュメントを読めばわかるものは学習コストも低いので恩恵に預かりましょう。

どうしてもオーバーテクノロジーを使いたい場合

• その書き方をすることで教授できるメリットが、簡単な書き方をするよりも圧倒的に大きい場合。
• 必ずコードの中に解説のコメントを残す（参考ドキュメントも）
• 使用例を残す
• 中身を意識しなくていいように書く
• 後任がそのファイルに変更を加える必要がでてきて、どうしてもわからないなら消せばOKな作りにする（代替可能）

なんでこんなことを決めるのか

感覚的にこれはダメこれはいいと都度決めていると、コストだし認識にズレが生じて無駄な手戻りが発生します。 事前にルールや基準を決めておくことで、実装ごとに議論する必要がなくなります。

人材的な背景

AIESECという団体は、４年で人が入れ替わる。 エンジニア人材も全国に毎年1,2人程度いれば良い方です。（2021年現在）
HPを内製しメンテナンスし続けていくためには、 興味がある人を教育してメンテナンスができるようになってもらう工程が必要になる。

そのため、このページを初めとするコードの管理も初心者→初級者が行っていくと想定される。

作り手にとって簡易なコード≠読みやすいコード

とはいえ、初心者であることを理由にあまりに簡単なコードを書きすぎると、 今できる人の生産性を著しく下げ、数ヶ月後負債だらけになりバグの温床となりメンテナンスコストが爆増するという地獄を見ることになります。

作る人にとって簡単なコードは読む人にとっては簡単ではないことが多いです。 読む人が読みやすいコードを作るのは初心者でもできると思うので意識しましょう。

必ず実装コストは増えていく

必ず、長期的に運用していくと新規に何かを作るコストは上がっていきます。 そのコストをいかに抑えるかがプログラマの仕事です。

これを無視してしまうと、今と未来の生産性を落とすのでいい塩梅を考えたいです

参考

和田卓人さんの資料

コードを読む人のレベル想定

誰のために。 誰をターゲットと置くのか。 誰にとって読みやすいコードなのかを定義します。

対象

• 本業エンジニアではなく、アイセックの現役メンバー
• プログラミングは勉強し始めて半年程度。
• vue,nuxtのコンポーネントはすでに５個以上は自分の力だけで作ったことがある。(SCSS,JSを使っている)
• →vueの基本的な性能(data,method,computed)を一度でも使ったコードを書いたことがある
• WebAppで言うならば、テンプレに沿った最低限の機能でいいので1人でCRUD機能を実装できる人。

まとめると「1人でHPメンテナンスが出来る人」です。

対象外

• プログラミングを学び始め、vueのコンポーネントは一つ作ったことがある。(初学者)
• 他のフレームワークで十分フロントのデータの受け渡しやアーキテクチャを理解しており、vueもドキュメントを読めばすぐに応用的な使い方でかける（vueのみ初学者）

対象の背景

• そもそも、全くの初心者だと自力でHPの改修・メンテナンスを行うこと自体が難しいので、対象外としたい。
• → Methodわからないです:大泣き:と言ってる人は、そもそも出来る人が居なくなったら、1人でHPをメンテナンスするのは不可能なのでは？という意見
• → 要件定義、開発のHOWを考えるができず、よくわからないコピペプログラミングで後世の担当者が地獄を見るような実装にしたら本末転倒（今のaiesecサーバーがその状態になってしまっている）

以上の理由から「1人でHPメンテナンスが出来る。」というところを最低ラインに引いていいんじゃないかなと思っているのです。