読まれるコードを書く

// 何が入っているか分からない
const d = new Date();
const list = await fetch(...);
function check(x) { ... }
 
// 読めば分かる
const publishedAt = new Date();
const pendingOrders = await fetch(...);
function isEligibleForDiscount(order) { ... }

// 3600 は秒？ ミリ秒？ 分？
const timeout = 3600;
 
// 迷わない
const timeoutSeconds = 3600;
const timeoutMs = 3_600_000;

// ネストが深い
function apply(user, coupon) {
  if (user !== null) {
    if (user.isActive) {
      if (coupon.isValid) {
        return discount(user, coupon);
      } else {
        throw new Error('クーポンが無効です');
      }
    } else {
      throw new Error('アカウントが停止中です');
    }
  } else {
    throw new Error('ユーザーが見つかりません');
  }
}
 
// 例外を先に片付ける
function apply(user, coupon) {
  if (user === null) throw new Error('ユーザーが見つかりません');
  if (!user.isActive) throw new Error('アカウントが停止中です');
  if (!coupon.isValid) throw new Error('クーポンが無効です');
 
  return discount(user, coupon);
}

// 呼び出し側で順番を間違える
createOrder(userId, itemId, 2, true, false, null);
 
// 何を渡しているか読める
createOrder({
  userId,
  itemId,
  quantity: 2,
  isGift: true,
  useCoupon: false,
});

// 悪い: コードを読めば分かることを繰り返している
// ユーザーIDでユーザーを取得する
const user = await getUser(userId);
 
// 良い: なぜそうしたかが書いてある
// 決済APIが2秒でタイムアウトするため、それより短く設定している
const timeoutMs = 1500;

// 悪い: 誰がいつやるのか分からず、永久に残る
// TODO: あとで直す
 
// 良い: 追跡できる
// TODO(PROJ-123): 決済APIのv2移行時にリトライ処理を削除する

// 最悪: 何が起きたか永久に分からなくなる
try {
  await savePayment(order);
} catch (e) {
  // 握り潰し
}
 
// 悪い: ログはあるが、呼び出し側は成功したと思っている
try {
  await savePayment(order);
} catch (e) {
  console.log(e);
}
 
// 良い: 記録して、呼び出し側に伝える
try {
  await savePayment(order);
} catch (error) {
  logger.error('決済の保存に失敗', { orderId: order.id, error });
  throw new PaymentSaveError(order.id, { cause: error });
}

// 検索しづらい
logger.info(`user ${userId} ordered item ${itemId}`);
 
// 絞り込み・集計ができる
logger.info('order created', { userId, itemId, amount, orderId });

test('クーポンを適用すると10%引きになる', () => {
  // Arrange（準備）
  const order = createOrder({ subtotal: 1000 });
  const coupon = createCoupon({ rate: 0.1 });
 
  // Act（実行）
  const result = applyCoupon(order, coupon);
 
  // Assert（検証）
  expect(result.total).toBe(900);
});

// これが何をテストしているか、名前だけで分かる
test('在庫が0の商品はカートに追加できない', ...)
test('同じクーポンは2回使えない', ...)

// 動くけれど、本番では怖い
const result = await externalApi.call(payload);
 
// 失敗と遅延を織り込んでいる
const result = await withTimeout(
  () => externalApi.call(payload),
  { timeoutMs: 1500, retries: 2, onRetry: (n) => logger.warn('retrying', { n }) },
);