s平面の左側

左側なので安定してます(制御工学の話は出てきません)

コーディングするとき・プルリクにコメントするときの観点

2年目、3年目と時が経つにつれて、他人が書いたコード見てコメントをする機会は増えていく。

このときに(主にコーディングに関する)自分の考え方を言語化して他人に伝える、というのはとても骨が折れる作業だ。

そこで、これまでに他人にしてきたコメントを思い返しつつ「普段どんなことを考えながらコーディングしているか」「プルリクを見るときにどんなところを見ているか」という観点を整理してみた。

もちろんただ文字に起こしただけでは伝わらない。 何度も繰り返し改善案のコードとセットにして伝える、という積み重ねの先に観点・感覚が身につくはずだと信じている。

※この記事では主に「バグが発生しにくいこと」「バグが発生しても原因を特定しやすいこと」を目的としている。

※具体的なコード例を載せると長くなるので割愛。文字での説明のみ。わかりにくいのは承知の上。

目次

名付けについて

  • 理解までの時間が最短か
  • 実態を表しているか
  • 誤解を生まないか

正直これについては、感覚的な部分や語彙力(英語)に依存する部分であるので、コメントしたからと言って一朝一夕で身につくものではない。

習慣として他人が書いた「筋の良い」コードを読むのが力を身につけるための王道だろうか。

引数について

  • 引数によって過剰に挙動を制御していないか
  • メソッド名から引数を予想できるか(最も自然な引数になっているか、驚き最小の法則)

前者については別のメソッドやクラスに切り分けよう。

戻り値について

  • 失敗を表すのに null や false を使っていないか
  • 空の結果を返すのに null や false を使ってないか
  • 戻り値に型が混在していないか

1 つめについては例外を使いましょう、というお話。 null や false では「その時点」ではプログラムが動き続けてしまう。 もし戻り値チェックが行われなかったらおかしなデータのまま後段の処理に進んでしまい予期せぬ挙動を引き起こす原因になる。

2 つめについては空配列や空文字列を使いましょう、というお話。 ただし数値の場合は議論の余地があり、場合によって null を使うのもやむなし、ということもある(0 や負値をとり得る数値の場合)。

データとその型には意味があって、意味に沿ったプログラミングをすれば記述は自然なものになる。 null や false を返していたら都度戻り値チェックをしなければいけないが、空配列を返しているなら、配列が来ることを想定している後段の処理にそのまま渡して問題ない(場合が多い)。

余分な処理が増えれば当然コーディングの量が増えて生産性は下がるし、バグが入り込む余地も増える。

3 つめは「処理の結果によって数値が返ってきたり、配列が返ってきたりする」みたいなことになっていないか、というお話。 実は2つめの内容を内包している。

期待される型が 1 つだけなら、後段の処理も1種類の型を想定すれば済む。

オブジェクト指向プログラミングなら継承の仕組みもうまく使いたいところ。

例外について

  • 例外を握りつぶしていないか
  • 失敗等のときにすぐに例外を投げているか

パフォーマンス面を気にするのであれば、また事情は変わってくるが。

責任範囲について

  • 1 メソッドが大きすぎないか
  • 複数箇所のデータにアクセスしていないか
  • 一言で表すことができる名前をつけられるか

名付けに悩んで良い答えが出ないときは、往々にして設計を見直したほうが良いという場合がある。

既存のプログラムについて

  • すでに「それ」を実現できる組み込みまたは公開されている関数・クラスはないか(車輪の再発明
  • 低レイヤーの処理をよしなに wrap してくれているものはないか
  • 既存のものを使うとき、「イケてない」仕様を wrap してあげられないか

2 つめの例を挙げるなら PHP における curl に対する Guzzle のようなもの。

その他

  • 余分な処理をしていないか
  • ネストを少なくできないか
  • クラスやメソッドの階層・粒度が一致しているか
  • 処理が何かの文脈に依存していないか

3 つめの話は設計の領域に入ってくるので、少し抽象度が高く伝わりにくいかも。

4 つめは「暗黙の前提条件を満たさないと正しく動かない」ということがないか、というお話。

「メソッド B は先にメソッド A を呼び出してから使わなければいけない」とか。 この場合、メソッド A の戻り値となるクラスの方にメソッド B を生やすなどして、間違って使われる余地が少なくなるような設計にすると良い。

その他、感覚レベルの話(オカルト含む)

  • コードの文字の密度が高すぎないか

→ 集中力が分散し、「見落とし」が起こりやすくなる。

  • コードに対称性はあるか

→ 対称性があると「異物」を見つけやすい。前節で説明した「階層」「粒度」が揃っているかが分かりやすい。

  • ざっと見渡したときに「違和感」がないか

→ ここまでに説明した内容が守られていると、コードは「美しい」

余談

ここまでまとめてきた内容は、概ね次の3つの資料でカバーされていると思う。

勉強会「Rails 5.1 + Webpacker + Vue.js 入門」にいってきた

イベント概要

connpass.com

普段触っているのは Rails ではないものの webpack + Vue.js の事例が知りたかったのと、「お話する内容」の

主に jQuery ベースのコードを Vue.js を用いて書き換えたい人向けにお話します。

に惹かれて参加。

所感

具体的なソースコードがあるのがとても良い。

github.com

ver0 というタグが jQuery ベースの状態で、そこから jQuery を抜いていく。

しかしそれを事前情報で知れなかったのと、会場で wifi が利用できなかったので、その場で手を動かしながらついていくのは断念。事前に情報として知らせてほしかった。

Rails や yarn が動く環境が必要だった)

内容としては感覚的に 6 割 Rails 固有の話、残りが Vue.js の話という感じで得たいと思った情報はそれほど得られなかった。(ある程度覚悟の上だったので、不満はない)

逆に言えば webpacker(Rails 用に webpack を使うための gem)の設定など、Rails に特化させて必要な手間をできるだけ省こうとするのは Rails の思想らしいといえばらしいと思った。

得た情報

  • webpack ではエントリーとなる js ファイルが重要
  • vue.esm の esm は ES modules の略(ES で書く際にはこちらを使う)
  • webpack-dev-server: 自動ビルド・シンタックスエラーを検出してくれる
  • Turbolinks: Rails のページ表示高速化のための何か(Vue.js とは相性が悪いということで今回は外す手順を踏んでいた)
  • vue-data-scooper: form に予め入っている値で Vue.js の data プロパティを初期化してくれるパッケージ(今回の勉強会主催者である黒田さんが作ったもの。yarn で入れられる)
  • Vue.js の v-cloak ディレクティブを使うと Vue インスタンスコンパイルが完了するまで画面に表示しない、とかができる
  • web アプリケーションフレームワークが提供するレンダリングエンジンと、 Vue.js のレンダリングをどう使い分ける?→インタラクティブなことをやるところは Vue.js のものを使って、残りは web アプリケーションフレームワークが提供するレンダリングでいいのでは(すべてを Vue.js に置き換えるのはけっこうたいへん)

余談

上記ソースコードsfc ブランチはレンダリングをすべて Vue.js で行おうとしているバージョンになっている。

バリデーションとかが大変そう。

【資料あり】Vue.js 入門の勉強会の講師をやってみた

少し前になるが、Vue.js に関する勉強会の講師というものをやってみた。

そのときに使用した資料がこちら。

github.com

私自身フロント側のプログラムなんて全然触ってきていないし、Vue.js についても個人的に数日触っただけだが、 触ってみたときにはかなりの感動があったし、私と同じレベル感で Vue.js(あるいはJSフレームワーク)に興味はあるけど触る機会を得られていない人も結構いるのではないかと思ってこのテーマを選んだ。

心がけたこと

準備をするにあたって以下の3点を意識した。

  • 実際に手を動かしてもらう内容にすること
  • どの環境でもすぐに動かせること
  • 参加者の期待値を調整しておくこと

実際に手を動かしてもらう内容にすること

普段勉強会に参加していて思うのは、話を聞くだけでは「わかった気になる」だけで何も身にもつかないよなぁ、ということ。

もちろん優秀な人というのは得た知識について、早速手を動かして試して自分のものにしていく。

だけど、就活・研究・業務が忙しいとかの事情もあるだろうし、ついつい後回しにしてそのまま……ということになってしまうこともあるだろう。

私自身面倒くさがりなのでTODOリストの「あとでやる」に残り続けることも珍しくないのでその気持ちはよく分かる。

せっかく参加してくれたのだから是非「体験する」までやって欲しい、ということでその場で手を動かすハンズオン形式にしようと思った。

どの環境でもすぐに動かせること

ハンズオン形式にしたときに問題となるのが環境差異や準備のこと。

勉強会自体30〜40分と短めの時間で、かつ参加者もどれくらいの人数になるかは未知数だったので、 環境構築に手間取る人が出て時間が取られることは極力避けたかった。

Vue.js については他のJSフレームワーク同様 npm からインストールして云々という構築方法もあるが、jQuery や Bootstrap のように CDN から読み込んで使うという方法も提供されている。 (このお手軽さが Vue.js の魅力のひとつだと思っているし、実はこういう背景があったから題材に Vue.js を選んだという部分もある)

これならネット環境とインターネットブラウザとテキストエディタさえあれば、(おそらく)あとはどんな環境でも動く。

実際に当日はこのような問題で進行が止まることはなかった。

参加者の期待値を調整しておくこと

次に避けたかった問題は、すでに入門レベルは終えている人が来て「それ知ってるよ」な内容になってしまうことだった。

こうなってしまっては、講師にとっては何も価値を生み出せない、参加者にとっては時間の無駄、さらに一連の勉強会に「レベルが低い」というレッテルを貼られてしまっては講師を努めている他の方にとってもマイナスになってしまい誰も幸せにならない。

これへの対策は、単純に勉強会の募集内容に「勉強会のゴール」と「対象と『しない』内容」を明記したこと。

supporterzcolab.com

【勉強会のゴール】
* Vue.js を使って動くページを作ってみる
* なんだか JS フレームワーク良さそうと思える

【対象と「しない」内容】
* 昨今のフロントエンド界隈のお話
* デザインやUI/UXについて
* Vue.js の活用事例

※実は勉強会ページにはしっかり「UI/UX」のタグが付けられてしまっていたりする(笑)

その結果については肌感でしか語れないが、参加者の9割近くは想定したレベルの人が集まっていたのではないかと思う。

もちろん、もう少しレベルの高い内容を希望する声や、逆についていくことができなかったという声も頂いたので、募集の文言については改善の余地はあるだろう。

前者については具体的な成果物を見せて「このレベルの内容をやります」と明記することなどが考えられる。

後者については「前提となる知識」といった項目を追加することが考えられる。

やってみて思ったこと

最終的に30名弱の方に参加していただいた。

懇親会でも参加者の側から話しかけてくださり、普段の懇親会では人に話しかけるのに緊張しまくる私にとっては非常に有難かった。

冒頭でも述べた通り、私自身普段は Vue.js はおろか普通に JavaScript さえなかなか触らないレベルの人間だが、 「実力・知識がないから、講師なんてやれない」というより、「実力・知識がないからこそ、講師をやっていったほうがいい」と思った。

レベルについては前述の期待値調整次第だと思うし、月並みな物言いにはなるが、人に向けてアウトプットすることで自分の知識を体系立てて整理できるので学習の過程において大きな効果があると思う。

さらには同じレベル(であろう)人たちとのつながりができたり、同じようなことで悩んでいる人がいることが知れて元気づけられたりと、人の面でも非常に意義があるものになったと思う。

また機会があれば積極的にやっていきたい。