はじめに
コードは他の開発者（未来の自分を含む）が読むものです。動作するコードを書くことは最低限の要求であり、真に価値のあるコードは「読みやすく、理解しやすく、変更しやすい」コードです。本記事では、『リーダブルコード』の原則をTypeScriptの文脈で実践的に解説します。
1. 名前付けの技術
明確で具体的な名前を選ぶ
// ❌ 悪い例
const d = new Date();
const yrs = calcAge(d);
// ✅ 良い例
const currentDate = new Date();
const userAgeInYears = calculateAge(currentDate);
検索しやすい名前を使う
// ❌ 悪い例
setTimeout(() => {
processData();
}, 86400000); // 何の数字？
// ✅ 良い例
const MILLISECONDS_IN_A_DAY = 86400000;
setTimeout(() => {
processData();
}, MILLISECONDS_IN_A_DAY);
境界値を明確にする
// ❌ 曖昧
interface Config {
maxItems: number; // 含む？含まない？
}
// ✅ 明確
interface Config {
maxItemsInclusive: number; // 最大値を含む
// または
itemLimit: number; // この値未満
}
2. 美しいコードフォーマット
一貫性のあるインデントとスペーシング
// ✅ 関連する要素をグループ化
class UserService {
private readonly userRepository: UserRepository;
private readonly emailService: EmailService;
constructor(
userRepository: UserRepository,
emailService: EmailService
) {
this.userRepository = userRepository;
this.emailService = emailService;
}
async createUser(userData: CreateUserDto): Promise<User> {
// バリデーション
this.validateUserData(userData);
// ユーザー作成
const user = await this.userRepository.create(userData);
// 通知送信
await this.emailService.sendWelcomeEmail(user.email);
return user;
}
}
3. コメントの適切な使用
なぜ（Why）を説明する
// ❌ 何をしているかの説明（コードを読めばわかる）
// ユーザーIDをインクリメント
userId++;
// ✅ なぜそうするのかを説明
// レガシーシステムとの互換性のため、IDは1から始まる必要がある
userId++;
TODOコメントは具体的に
// ❌ 曖昧なTODO
// TODO: エラーハンドリングを改善
// ✅ 具体的なTODO
// TODO(tanaka): 2024-04-01までに、DBタイムアウトエラーに対するリトライ機能を実装
// 関連チケット: JIRA-1234
4. 制御フローの簡潔化
早期リターンで入れ子を減らす
// ❌ 深い入れ子
function processUser(user: User | null): string {
if (user !== null) {
if (user.isActive) {
if (user.hasPermission) {
return `Processing ${user.name}`;
} else {
return 'No permission';
}
} else {
return 'User inactive';
}
} else {
return 'User not found';
}
}
// ✅ 早期リターン
function processUser(user: User | null): string {
if (!user) return 'User not found';
if (!user.isActive) return 'User inactive';
if (!user.hasPermission) return 'No permission';
return `Processing ${user.name}`;
}
条件式の順序
// ✅ 肯定的な条件を先に、単純な条件を先に
if (user.isActive && user.age >= 18) {
// 通常の処理
} else {
// エラー処理
}
5. 変数とスコープ
変数のスコープを最小限に
// ❌ 広すぎるスコープ
let total = 0;
let items: Item[] = [];
function calculateTotal() {
items = fetchItems();
total = items.reduce((sum, item) => sum + item.price, 0);
}
// ✅ 必要最小限のスコープ
function calculateTotal(): number {
const items = fetchItems();
const total = items.reduce((sum, item) => sum + item.price, 0);
return total;
}
一時変数を削除
// ❌ 不要な一時変数
const isUserValid = user.age >= 18 && user.isVerified;
if (isUserValid) {
// ...
}
// ✅ 直接使用（意味が明確な場合）
if (user.age >= 18 && user.isVerified) {
// ...
}
// ✅ または説明的な関数として抽出
function isAdultAndVerified(user: User): boolean {
return user.age >= 18 && user.isVerified;
}
6. コードの再構成
関数の抽出
// ❌ 長い関数
async function processOrder(order: Order): Promise<void> {
// 在庫確認
for (const item of order.items) {
const stock = await getStock(item.productId);
if (stock < item.quantity) {
throw new Error(`Insufficient stock for ${item.productId}`);
}
}
// 価格計算
let total = 0;
for (const item of order.items) {
const price = await getPrice(item.productId);
total += price * item.quantity;
}
// 注文処理
// ... 長い処理
}
// ✅ 小さな関数に分割
async function processOrder(order: Order): Promise<void> {
await validateStock(order.items);
const total = await calculateTotal(order.items);
await createOrder(order, total);
}
async function validateStock(items: OrderItem[]): Promise<void> {
for (const item of items) {
const stock = await getStock(item.productId);
if (stock < item.quantity) {
throw new InsufficientStockError(item.productId);
}
}
}
async function calculateTotal(items: OrderItem[]): Promise<number> {
let total = 0;
for (const item of items) {
const price = await getPrice(item.productId);
total += price * item.quantity;
}
return total;
}
重複の排除
// ❌ 重複したロジック
function validateEmail(email: string): boolean {
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
return emailRegex.test(email);
}
function validateUserEmail(user: User): boolean {
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
return emailRegex.test(user.email);
}
// ✅ 共通化
const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
function isValidEmail(email: string): boolean {
return EMAIL_REGEX.test(email);
}
function validateUserEmail(user: User): boolean {
return isValidEmail(user.email);
}
7. テストを意識したコード
テストしやすい関数設計
// ❌ テストが困難
class OrderService {
async processOrder(orderId: string): Promise<void> {
const order = await database.getOrder(orderId);
const user = await database.getUser(order.userId);
// 直接メール送信
await sendEmail(user.email, 'Order processed');
// 直接データベース更新
await database.updateOrder(orderId, { status: 'processed' });
}
}
// ✅ 依存性注入でテスト可能に
class OrderService {
constructor(
private orderRepository: OrderRepository,
private userRepository: UserRepository,
private emailService: EmailService
) {}
async processOrder(orderId: string): Promise<void> {
const order = await this.orderRepository.findById(orderId);
const user = await this.userRepository.findById(order.userId);
await this.emailService.sendOrderConfirmation(user.email);
await this.orderRepository.updateStatus(orderId, 'processed');
}
}
8. エラーハンドリング
明確なエラーメッセージ
// ❌ 曖昧なエラー
throw new Error('Invalid input');
// ✅ 具体的なエラー
throw new ValidationError(
`Invalid email format: "${email}". Expected format: user@example.com`
);
カスタムエラークラス
// ✅ ドメイン固有のエラー
class InsufficientStockError extends Error {
constructor(
public readonly productId: string,
public readonly requested: number,
public readonly available: number
) {
super(
`Insufficient stock for product ${productId}: ` +
`requested ${requested}, available ${available}`
);
this.name = 'InsufficientStockError';
}
}
// 使用例
if (stock < requested) {
throw new InsufficientStockError(productId, requested, stock);
}
9. 巨大な式の分割
説明変数の導入
// ❌ 複雑な条件式
if (user.registrationDate > new Date('2023-01-01') &&
user.purchases.length > 5 &&
user.purchases.reduce((sum, p) => sum + p.amount, 0) > 1000) {
// プレミアムユーザー処理
}
// ✅ 説明変数で意図を明確に
const isNewUser = user.registrationDate > new Date('2023-01-01');
const hasMultiplePurchases = user.purchases.length > 5;
const totalPurchaseAmount = user.purchases.reduce((sum, p) => sum + p.amount, 0);
const isHighValueCustomer = totalPurchaseAmount > 1000;
if (isNewUser && hasMultiplePurchases && isHighValueCustomer) {
// プレミアムユーザー処理
}
ド・モルガンの法則を使った簡潔化
// ❌ 理解しにくい否定条件
if (!(isValid && isEnabled)) {
return;
}
// ✅ ド・モルガンの法則で簡潔に
if (!isValid || !isEnabled) {
return;
}
10. 型の活用
型エイリアスで意図を明確に
// ❌ プリミティブ型の直接使用
function calculateAge(birthYear: number): number {
return new Date().getFullYear() - birthYear;
}
// ✅ 型エイリアスで意図を表現
type Year = number;
type Age = number;
function calculateAge(birthYear: Year): Age {
return new Date().getFullYear() - birthYear;
}
ユニオン型で状態を表現
// ✅ 明確な状態管理
type LoadingState = {
status: 'loading';
};
type SuccessState<T> = {
status: 'success';
data: T;
};
type ErrorState = {
status: 'error';
error: Error;
};
type DataState<T> = LoadingState | SuccessState<T> | ErrorState;
// 使用例
function renderUserProfile(state: DataState<User>) {
switch (state.status) {
case 'loading':
return <Spinner />;
case 'success':
return <UserProfile user={state.data} />;
case 'error':
return <ErrorMessage error={state.error} />;
}
}
11. 一度に一つのことを
タスクの分離
// ❌ 複数の責任を持つ関数
function updateUserAndSendNotification(userId: string, data: UpdateData) {
// ユーザー検証
const user = getUser(userId);
if (!user) throw new Error('User not found');
// データ更新
user.name = data.name;
user.email = data.email;
user.updatedAt = new Date();
// ログ記録
console.log(`User ${userId} updated`);
// メール送信
sendEmail(user.email, 'Profile updated');
// データベース保存
saveUser(user);
}
// ✅ 単一責任の原則
function validateUser(userId: string): User {
const user = getUser(userId);
if (!user) throw new UserNotFoundError(userId);
return user;
}
function updateUserData(user: User, data: UpdateData): User {
return {
...user,
...data,
updatedAt: new Date()
};
}
function notifyUserUpdate(user: User): void {
sendEmail(user.email, 'Profile updated');
}
// 使用時
async function handleUserUpdate(userId: string, data: UpdateData) {
const user = validateUser(userId);
const updatedUser = updateUserData(user, data);
await saveUser(updatedUser);
await notifyUserUpdate(updatedUser);
logger.info(`User ${userId} updated`);
}
12. 短いコードより分かりやすいコード
可読性を優先
// ❌ 短いが理解しにくい
const a = u.filter(x => x.a && x.s > 18).map(x => x.n);
// ✅ 長いが理解しやすい
const activeAdultUsers = users
.filter(user => user.isActive && user.age > 18)
.map(user => user.name);
賢すぎるコードを避ける
// ❌ トリッキーなワンライナー
const result = (x => (y => x * y)(2))(3); // 6
// ✅ 単純明快
const multiplyBy2 = (x: number) => x * 2;
const result = multiplyBy2(3); // 6
13. コードに書かれていないことを読み取る
境界条件の明確化
// ❌ 境界条件が不明確
function getItems(count: number): Item[] {
// countが0の場合は？負の場合は？
return items.slice(0, count);
}
// ✅ 境界条件を明確に
function getItems(count: number): Item[] {
if (count < 0) {
throw new InvalidArgumentError('Count must be non-negative');
}
if (count === 0) {
return [];
}
return items.slice(0, Math.min(count, items.length));
}
戻り値の意味を明確に
// ❌ nullの意味が不明確
function findUser(id: string): User | null {
// nullは「見つからない」？「エラー」？
return database.find(id);
}
// ✅ Result型で意図を明確に
type Result<T, E = Error> =
| { success: true; value: T }
| { success: false; error: E };
function findUser(id: string): Result<User, UserError> {
try {
const user = database.find(id);
if (!user) {
return {
success: false,
error: new UserNotFoundError(id)
};
}
return { success: true, value: user };
} catch (error) {
return {
success: false,
error: new DatabaseError(error)
};
}
}
14. ライブラリを知る
標準ライブラリの活用
// ❌ 車輪の再発明
function removeWhitespace(str: string): string {
let result = '';
for (const char of str) {
if (char !== ' ' && char !== '\t' && char !== '\n') {
result += char;
}
}
return result;
}
// ✅ 標準メソッドを活用
function removeWhitespace(str: string): string {
return str.replace(/\s/g, '');
}
配列メソッドの適切な使用
// ❌ forループでの実装
let hasExpensiveItem = false;
for (const item of items) {
if (item.price > 1000) {
hasExpensiveItem = true;
break;
}
}
// ✅ 適切な配列メソッド
const hasExpensiveItem = items.some(item => item.price > 1000);
// その他の便利なメソッド
const allItemsInStock = items.every(item => item.inStock);
const expensiveItems = items.filter(item => item.price > 1000);
const totalPrice = items.reduce((sum, item) => sum + item.price, 0);
15. 無関係の下位問題を抽出する
ユーティリティ関数の抽出
// ❌ ビジネスロジックに混在する汎用処理
function processOrder(order: Order) {
// 日付フォーマット処理がビジネスロジックに混在
const orderDate = new Date(order.createdAt);
const formattedDate = `${orderDate.getFullYear()}-${
String(orderDate.getMonth() + 1).padStart(2, '0')
}-${String(orderDate.getDate()).padStart(2, '0')}`;
console.log(`Processing order from ${formattedDate}`);
// ... ビジネスロジック
}
// ✅ 汎用処理を分離
function formatDate(date: Date, format: string = 'YYYY-MM-DD'): string {
const year = date.getFullYear();
const month = String(date.getMonth() + 1).padStart(2, '0');
const day = String(date.getDate()).padStart(2, '0');
return format
.replace('YYYY', String(year))
.replace('MM', month)
.replace('DD', day);
}
function processOrder(order: Order) {
const formattedDate = formatDate(new Date(order.createdAt));
console.log(`Processing order from ${formattedDate}`);
// ... ビジネスロジック
}
16. 汎用コードを特殊化する
ジェネリックの適切な使用
// ❌ 過度に汎用的
function processData<T, U, V>(
data: T,
transformer: (t: T) => U,
validator: (u: U) => boolean,
processor: (u: U) => V
): V | null {
const transformed = transformer(data);
if (validator(transformed)) {
return processor(transformed);
}
return null;
}
// ✅ 用途に特化
interface OrderData {
items: string[];
total: number;
}
interface ValidatedOrder {
items: OrderItem[];
total: number;
tax: number;
}
function processOrder(orderData: OrderData): ValidatedOrder | null {
const validatedOrder = validateOrder(orderData);
if (validatedOrder) {
return calculateOrderTotals(validatedOrder);
}
return null;
}
まとめ
リーダブルなコードを書くことは、チーム開発において最も重要なスキルの一つです。以下の原則を常に意識しましょう：
- 名前は投資 - 良い名前を考える時間は、後で節約できる時間より遥かに少ない
- シンプルに保つ - 複雑な解決策より、シンプルで理解しやすい解決策を選ぶ
- 一貫性を保つ - チーム内でスタイルガイドを統一し、一貫性のあるコードを書く
- リファクタリングを恐れない - コードは生き物。常に改善の余地がある
- レビューを大切に - 他者の視点は、自分では気づかない問題を発見してくれる
これらの原則を実践することで、保守性が高く、バグの少ない、チームメンバー全員が理解できるコードベースを構築できるでしょう。