よいコーディングとは - 可読性・保守性を高めるベストプラクティスと設計原則

1
2
3
4
5
6
7
8
9

# 悪い例: 意図が不明
d = 86400
data = get_data()
temp = process(data)

# 良い例: 意図が明確
SECONDS_PER_DAY = 86400
user_transactions = fetch_user_transactions()
validated_transactions = validate_transactions(user_transactions)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

// 悪い例: 複数の責務を持つ長い関数
function processOrder(order) {
  // 1. バリデーション（30行）
  // 2. 在庫確認（20行）
  // 3. 決済処理（40行）
  // 4. メール送信（15行）
  // 5. ログ記録（10行）
}

// 良い例: 単一の責務を持つ小さな関数
function processOrder(order) {
  validateOrder(order);
  reserveInventory(order);
  processPayment(order);
  sendConfirmationEmail(order);
  logOrderProcessed(order);
}

1
2
3
4
5
6
7
8

// 悪い例: 引数が多すぎる
public void createUser(String firstName, String lastName, 
                       String email, String phone, 
                       String address, String city, 
                       String country, String postalCode) { }

// 良い例: パラメータオブジェクトを使用
public void createUser(UserRegistrationRequest request) { }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# 悪い例: 名前から予期しない副作用がある
def check_password(username, password):
    user = find_user(username)
    if user.password == hash(password):
        initialize_session(user)  # 副作用！
        return True
    return False

# 良い例: 関数名と動作が一致
def verify_password(username, password):
    user = find_user(username)
    return user.password == hash(password)

def login(username, password):
    if verify_password(username, password):
        initialize_session(find_user(username))
        return True
    return False

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 悪い例: 新しい形状を追加するたびに修正が必要
def calculate_area(shape):
    if shape.type == "circle":
        return 3.14 * shape.radius ** 2
    elif shape.type == "rectangle":
        return shape.width * shape.height
    # 新しい形状が追加されるたびにここを修正...

# 良い例: 新しい形状を追加しても修正不要
class Shape:
    def area(self):
        raise NotImplementedError

class Circle(Shape):
    def __init__(self, radius):
        self.radius = radius
    
    def area(self):
        return 3.14 * self.radius ** 2

class Rectangle(Shape):
    def __init__(self, width, height):
        self.width = width
        self.height = height
    
    def area(self):
        return self.width * self.height

def calculate_area(shape):
    return shape.area()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// 悪い例: Squareは Rectangleの契約を破る
class Rectangle {
    protected int width, height;
    
    public void setWidth(int w) { width = w; }
    public void setHeight(int h) { height = h; }
    public int area() { return width * height; }
}

class Square extends Rectangle {
    // 正方形なので幅と高さを同時に変更
    public void setWidth(int w) { width = w; height = w; }
    public void setHeight(int h) { width = h; height = h; }
    // これは親クラスの期待する動作と異なる！
}

// 良い例: 共通インターフェースを使用
interface Shape {
    int area();
}

class Rectangle implements Shape { /* ... */ }
class Square implements Shape { /* ... */ }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

// 悪い例: すべての機能を持つ巨大インターフェース
interface Worker {
  work(): void;
  eat(): void;
  sleep(): void;
  attendMeeting(): void;
}

// ロボットはeatやsleepを実装できない
class Robot implements Worker {
  work() { /* OK */ }
  eat() { throw new Error("Robots don't eat"); }  // 問題！
  sleep() { throw new Error("Robots don't sleep"); }  // 問題！
  attendMeeting() { /* OK */ }
}

// 良い例: 役割ごとにインターフェースを分離
interface Workable {
  work(): void;
}

interface Feedable {
  eat(): void;
}

interface Restable {
  sleep(): void;
}

class Robot implements Workable {
  work() { /* OK */ }
}

class Human implements Workable, Feedable, Restable {
  work() { /* ... */ }
  eat() { /* ... */ }
  sleep() { /* ... */ }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// 悪い例: 重複したバリデーションロジック
function validateEmail(email) {
  const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return regex.test(email);
}

function validateContactForm(form) {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;  // 重複！
  if (!emailRegex.test(form.email)) {
    return false;
  }
  // ...
}

// 良い例: 単一のバリデーション関数を再利用
function validateEmail(email) {
  const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return regex.test(email);
}

function validateContactForm(form) {
  if (!validateEmail(form.email)) {
    return false;
  }
  // ...
}

1
2
3
4
5
6
7

# 悪い例: 過度に複雑
def is_even(n):
    return not bool(n & 1) if isinstance(n, int) else None

# 良い例: シンプル
def is_even(n):
    return n % 2 == 0

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// 悪い例: 使われない汎用化
class DataExporter {
    public void exportToCSV(Data data) { /* ... */ }
    public void exportToJSON(Data data) { /* ... */ }
    public void exportToXML(Data data) { /* ... */ }
    public void exportToYAML(Data data) { /* ... */ }
    public void exportToProtobuf(Data data) { /* ... */ }
    // 実際に使うのはCSVだけ...
}

// 良い例: 必要なものだけ実装
class DataExporter {
    public void exportToCSV(Data data) { /* ... */ }
    // 他の形式が必要になったら追加
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// Before
function printOwing(invoice) {
  console.log("***********************");
  console.log("**** Customer Owes ****");
  console.log("***********************");

  let outstanding = 0;
  for (const order of invoice.orders) {
    outstanding += order.amount;
  }

  console.log(`name: ${invoice.customer}`);
  console.log(`amount: ${outstanding}`);
}

// After
function printOwing(invoice) {
  printBanner();
  const outstanding = calculateOutstanding(invoice);
  printDetails(invoice, outstanding);
}

function printBanner() {
  console.log("***********************");
  console.log("**** Customer Owes ****");
  console.log("***********************");
}

function calculateOutstanding(invoice) {
  return invoice.orders.reduce((sum, order) => sum + order.amount, 0);
}

function printDetails(invoice, outstanding) {
  console.log(`name: ${invoice.customer}`);
  console.log(`amount: ${outstanding}`);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Before
def calculate_price(quantity):
    return quantity * 9.81 * 100

# After
GRAVITATIONAL_CONSTANT = 9.81
PRICE_PER_UNIT = 100

def calculate_price(quantity):
    return quantity * GRAVITATIONAL_CONSTANT * PRICE_PER_UNIT

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// Before
function amountInvoiced(startDate: Date, endDate: Date): number { }
function amountReceived(startDate: Date, endDate: Date): number { }
function amountOverdue(startDate: Date, endDate: Date): number { }

// After
class DateRange {
  constructor(public start: Date, public end: Date) {}
}

function amountInvoiced(range: DateRange): number { }
function amountReceived(range: DateRange): number { }
function amountOverdue(range: DateRange): number { }

1
2
3
4
5
6
7

// 悪い例: コードを説明するコメント
// ユーザーが18歳以上かどうかをチェック
if (user.age >= 18) { }

// 良い例: コード自体が説明的
const LEGAL_AGE = 18;
if (user.age >= LEGAL_AGE) { }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 良いコメントの例

# RFC 5322に準拠したメールアドレスの正規表現
# 参考: https://www.rfc-editor.org/rfc/rfc5322
EMAIL_PATTERN = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'

# WARNING: この処理はO(n^2)の計算量を持つ。
# 1000件以上のデータでは別のアルゴリズムを検討すること。
def find_duplicates(items):
    # ...

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# GitHub Actionsでの自動チェック例
name: Code Quality
on: [pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run linter
        run: npm run lint
      - name: Run formatter check
        run: npm run format:check
      - name: Run type check
        run: npm run type-check