良いコードの書き方 - Wiz テックブログ

こんにちは！

フロントエンドエンジニアの松本です。

本日は「良いコードの書き方」と言うテーマでお話しさせていただきます。

コードサンプルはJavaScriptを採用しています。

本質的にはどの言語にも通ずるものがあるので、ぜひ最後までご覧ください。

そもそも良いコードとは🤔

まず、良いコードの条件は以下の2点です。

他の人が見ても短時間で理解しやすいコードを書く
他の人には"半年後"の自分も含まれる

オレオレ流の書き方ではなく、他人が短時間で理解できるようなコードがベストだと言う考え方です。

具体的なTipsを8つ紹介していきます。

1. 名前に情報を詰め込む📦

変数や関数などに適切な名前をつけましょう。

以下は卵かけご飯をオーダーする関数です。（卵かけご飯好き）

卵かけご飯好きには問題ないように見えますが、tkgは省略しすぎな気がします。

そもそも「何をするための関数なのか」が名前から全く想像できません。

const tkg = (hakumaiGram) => {
    return `白米${hakumaiGram}グラムで卵かけご飯をよろしく！`
}

tkg(200)  //白米200グラムで卵かけご飯をよろしく！

そこで、しかるべき「名前」を付けてあげました。

const tamagokakeGohanOrder = (hakumaiGram) => {
    return `白米${hakumaiGram}グラムで卵かけご飯をよろしく！`
}

tamagokakeGohanOrder(200)  //白米200グラムで卵かけご飯をよろしく！

関数名が多少長くなっても、名前から処理を想像できる関数名を付けましょう。

変数や関数名をやたらと省略せず、具体的で明確な単語を選ぶことで名前に情報を詰め込むことができます。

2. 美しさ🧝🏻‍♀️

見た目が美しい一貫性のあるレイアウトでコードを書きましょう。

具体的にはインデントを揃えるなどです。

フロントエンドであればPrettierを使いましょう。

prettier.io

3. コメントすべきことを知る💬

コメントの目的は、書き手の意図を読み手に知らせることです。

以下のように「見たら分かる」コメントは望ましくありません。

// 関数定義
const tkg = (hakumaiGram) => {
    return `白米${hakumaiGram}グラムで卵かけご飯をよろしく！`
}

// 実行
tkg(200)

以下のように後で手をつけたいところは、TODOとしてコメントを残しておくと良いでしょう。

// TODO:関数名がイケてない。もっと良い名前を
const tkg = (hakumaiGram) => {
    return `白米${hakumaiGram}グラムで卵かけご飯をよろしく！`
}

tkg(200)

TODOをハイライトしてくれる拡張機能も便利でオススメです。

marketplace.visualstudio.com

コメントには価値を持たせること、コードからすぐに分かることをコメントに書かないことを意識しましょう。

4. 制御フローを読みやすくする🚦

条件式の引数の並び順に気をつけましょう。

基本的に以下のような書き方が可読性も上がって良しです。

左側：「調査対象の式」変化する。
右側：「比較対象の式」あまり変化しない。

if (length >= 10)

直感的に判断できるものは、三項演算子で書いても良いでしょう。

time < 12 ? 'AM' : 'PM'

5. 変数と読みやすさ🔦

変数のスコープはできるだけ小さくしましょう。

以下は、トップレベルでグローバル変数を定義しているパターンです。

コードの行数が増えていくと、「どこで定義してどこで使われているのか」を探すだけでも時間がかかります。

const tamago = document.getElementById('tamago')
const gohan = document.getElementById('gohan')

const tamagoAction = () => {
    return tamago.textContent = '卵割れた'
}

const gohanAction = () => {
    return gohan.textContent = 'お米炊けた'
}

変数を実際に使われてる関数内に移動させて、スコープを小さくました。

「どこで使われているか」がより明確になりました。

const tamagoAction = () => {
    const tamago = document.getElementById('tamago')
    return tamago.textContent = '卵割れた'
}

const gohanAction = () => {
    const gohan = document.getElementById('gohan')
    return gohan.textContent = 'お米炊けた'
}

6. コードの再構成

エンジニアリングとは、大きな問題を小さな問題に分割することです。

以下のコードを見て見ましょう。

商品一覧のデータを取得して、DOMに描画する関数です。

一つの関数内で複数のタスクを行っており、見通しが悪いコードになっています。

基本的に一つの関数は一つの処理をすべきです。

export default async () => {
    const itemElement = document.getElementById('item')
    const ITEM = '/api/items'
    const res = await fetch(ITEM)
    const result = await res.json()
    /*
       ........
       ........
       resultを用いてDOMを組み立てるなが〜〜い記述
       ........
       ........
   */
    itemElement.innerHTML = renderDom
}

ここで役割を分割してみましょう。

以下はリファクタリングしたことで3つのコードに分割することができました。

商品一覧データを取得する関数
商品一覧のコンポーネントを描画する関数
DOMを生成する関数

const itemElement = document.getElementById('item')
const ITEM = '/api/items'

// 商品一覧のデータを取得する
const fetchItems = async (url) => {
  const res = await fetch(url)
  const result = await res.json()
  return result
}

// 商品一覧のコンポーネントを描画する関数
const renderItemComponent = async () => {
   const items = await fetchItems(ITEM)
   const renderDom = createItemDom(items)
   itemElement.innerHTML = renderDom
}

// オブジェクトからDOMを生成する
const createItemDom = (data) => {
 // ...DOMを組み立てるコード
}