コードに意味を与える技術

コードで伝えるエラー処理の意図 - 例外設計と戻り値による情報伝達

Tags: エラーハンドリング, 例外処理, 戻り値, Optional, Result, 可読性, 保守性, 設計

ソフトウェア開発において、エラーハンドリングは避けて通れない重要な要素です。しかし、単にエラーが発生しないようにするだけでなく、「なぜそのエラー処理が必要なのか」「エラーが発生した場合、システムはどう応答すべきなのか」といった設計者の意図をコードを通じて適切に伝えることは、コードの可読性、保守性、そして堅牢性に大きく寄与します。

本記事では、エラー処理におけるコードの意図伝達に焦点を当て、特に例外と戻り値を用いたアプローチについて、具体的なコード例を交えながら解説します。

エラー処理における「意図」を伝える重要性

コードにおけるエラー処理は、単に異常な状態に対処するための構文的な記述に留まりません。そこには、システムが予期せぬ状況にどのように応答するか、どのような種類の問題が発生しうるか、そしてその問題を検知した呼び出し元はどのように対応すべきか、といった設計思想と意図が込められています。

しかし、この意図が不明瞭なコードは、以下のような問題を引き起こします。

これらの問題を回避し、コードを通じて明確な意図を伝えることが、より信頼性の高い、チームにとって扱いやすいコードへと繋がります。

例外による意図伝達

例外（Exception）は、プログラムの通常の実行フローから外れる、予期しないエラー状態を示すための強力なメカニズムです。例外を使用することで、エラー発生箇所からその処理を担う箇所へ、エラー情報を効果的に「伝播」させることができます。

例外の種類と意図

例外を利用する際に重要なのは、どのような状況で、どのような種類の例外をスローするかです。Javaを例にとると、RuntimeExceptionのような非チェック例外と、IOExceptionのようなチェック例外があります。

適切な種類の例外を選択することで、「これは呼び出し元が対処すべき外部的な問題なのか、それとも開発者が修正すべき内部的なバグなのか」というエラーの性質と、それに対する期待される応答の意図を明確に伝えることができます。

具体的なエラー情報の伝達

例外オブジェクト自体に含める情報も、意図伝達に不可欠です。エラーメッセージはもちろん、原因となった別の例外（原因例外、Cause）、エラーコード、発生時刻などの情報を付加することで、エラー発生時の状況を詳細に伝えることができます。

Before: 情報が不足している例外

public User findUserById(long userId) {
    // ... ユーザー検索処理 ...
    if (user == null) {
        // ユーザーが見つからなかったという事実だけを伝える
        throw new RuntimeException("User not found.");
    }
    return user;
}

この例では、「ユーザーが見つからなかった」という事実は伝わりますが、どのIDのユーザーが見つからなかったのか、それがなぜ問題なのか、といった詳細な意図が伝わりません。

After: 意図を伝える例外

// 特定のビジネスエラーを示すカスタム例外
public class UserNotFoundException extends RuntimeException {
    private final long userId;

    public UserNotFoundException(long userId, String message) {
        super(message);
        this.userId = userId;
    }

    public long getUserId() {
        return userId;
    }
}

public User findUserById(long userId) {
    // ... ユーザー検索処理 ...
    if (user == null) {
        // どのユーザーIDで見つからなかったのか、カスタム例外で伝える
        throw new UserNotFoundException(userId, "User with ID " + userId + " not found.");
    }
    return user;
}

// 呼び出し元での利用例
try {
    User user = userService.findUserById(123L);
    // ...
} catch (UserNotFoundException e) {
    // どのIDのユーザーが見つからなかったかを取得し、ログ出力やユーザーへの通知に利用できる
    System.err.println("Error: " + e.getMessage() + " (User ID: " + e.getUserId() + ")");
    // ...
}

カスタム例外を使用し、エラーに関連する具体的な情報（ここではuserId）を含めることで、「ID userId のユーザーが見つからなかったため、後続処理を続行できない」という意図と、その原因となった具体的なデータが明確に伝わります。これにより、呼び出し元はより適切なエラーハンドリング（例: ユーザーへのエラー表示、ログの詳細化）を行うことができます。

戻り値による意図伝達

例外が「通常のフローからの脱出」を示すのに対し、戻り値は「処理の結果」を直接的に伝えます。エラー状態を戻り値で示すアプローチは、特に以下の意図を伝えるのに適しています。

Nullや特定の値によるエラー表現

エラーを表現するために、Nullや特定の値を戻す場合があります。これはシンプルですが、意図が不明瞭になりがちです。

Before: Nullでエラーを示す

// ユーザーが見つからなかった場合にnullを返す
public User findUserByName(String name) {
    // ... ユーザー検索処理 ...
    if (user == null) {
        return null; // ユーザーが見つからなかった
    }
    return user;
}

このコードはシンプルですが、Nullが返されたときに「ユーザーが見つからなかった」という意図が明確に伝わりません。呼び出し元は戻り値がNullかどうかを常にチェックする必要がありますが、そのNullが「見つからなかった」ことによるものか、あるいは別の原因（例: データベース接続エラーなど）によるものかを区別できません。また、Nullをチェックし忘れるとNullPointerExceptionの原因となります。

Optionalによる不在の表現

Java 8以降のOptionalは、「値が存在しない可能性がある」という意図を明確に伝えるための有効な手段です。

After: Optionalで不在を示す

// ユーザーが見つからなかった場合にOptional.empty()を返す
public Optional<User> findUserByName(String name) {
    // ... ユーザー検索処理 ...
    if (user == null) {
        return Optional.empty(); // 値が存在しない可能性を明示的に示す
    }
    return Optional.of(user);
}

// 呼び出し元での利用例
userService.findUserByName("Alice")
    .ifPresentOrElse(
        user -> {
            // ユーザーが存在する場合の処理
            System.out.println("Found user: " + user.getName());
        },
        () -> {
            // ユーザーが存在しない場合（Optional.empty()）の処理
            System.out.println("User not found.");
        }
    );

Optionalを返すことで、「このメソッドは成功するかもしれないし、しないかもしれない（その場合、戻り値は空になる）」という意図が明確になります。呼び出し元はisPresent()やifPresent()などのメソッドを使用して、値の存在を確認することが奨励され、NullPointerExceptionのリスクを減らしつつ、コードから「値が存在しない場合の処理が必要である」という意図を読み取ることができます。

Resultオブジェクトによる成否と詳細の表現

より複雑なエラー状態や、複数の異なる失敗理由を戻り値で表現したい場合は、成功時の値と失敗時のエラー情報を保持する専用のResultオブジェクト（あるいはEither型など）を使用するアプローチが有効です。

Before: 戻り値と例外が混在、または戻り値だけでは情報不足

// 成功時はtrue、ファイルが見つからない場合はfalse、その他のエラーは例外？
public boolean processFile(String filePath) throws IOException {
    File file = new File(filePath);
    if (!file.exists()) {
        return false; // ファイルなし
    }
    // ファイル読み込み処理...
    if (!file.canRead()) {
        throw new IOException("Cannot read file: " + filePath); // 読み込み権限なし
    }
    // 処理成功
    return true;
}

この例では、falseが返された理由が「ファイルが見つからない」ことなのか、他の理由なのかが不明瞭です。また、権限エラーは例外で表現されており、エラーの扱いが一貫していません。

After: Resultオブジェクトで意図を統一的に伝える

// 処理結果を表すクラス
public class Result<T, E> {
    private final T value;
    private final E error;
    private final boolean isSuccess;

    private Result(T value, E error, boolean isSuccess) {
        this.value = value;
        this.error = error;
        this.isSuccess = isSuccess;
    }

    public static <T, E> Result<T, E> success(T value) {
        return new Result<>(value, null, true);
    }

    public static <T, E> Result<T, E> failure(E error) {
        return new Result<>(null, error, false);
    }

    public boolean isSuccess() {
        return isSuccess;
    }

    public boolean isFailure() {
        return !isSuccess;
    }

    public T getValue() {
        if (!isSuccess) throw new IllegalStateException("Result is not success");
        return value;
    }

    public E getError() {
        if (isSuccess) throw new IllegalStateException("Result is not failure");
        return error;
    }
}

// ファイル処理の結果を表すenum
public enum FileProcessingError {
    FILE_NOT_FOUND,
    PERMISSION_DENIED,
    READ_ERROR,
    // ... 他のエラー
}

// 処理結果をResultオブジェクトで返す
public Result<Void, FileProcessingError> processFile(String filePath) {
    File file = new File(filePath);
    if (!file.exists()) {
        return Result.failure(FileProcessingError.FILE_NOT_FOUND); // ファイルが見つからない意図を明示
    }
    if (!file.canRead()) {
        return Result.failure(FileProcessingError.PERMISSION_DENIED); // 権限エラーの意図を明示
    }
    try {
        // ファイル読み込み・処理...
        // 成功した場合
        return Result.success(null); // 成功の意図を明示
    } catch (IOException e) {
        // 読み込みエラーの場合
        return Result.failure(FileProcessingError.READ_ERROR); // 読み込みエラーの意図を明示
    }
}

// 呼び出し元での利用例
Result<Void, FileProcessingError> result = fileProcessor.processFile("path/to/file.txt");

if (result.isSuccess()) {
    System.out.println("File processed successfully.");
} else {
    FileProcessingError error = result.getError();
    switch (error) {
        case FILE_NOT_FOUND:
            System.err.println("Error: File not found.");
            break;
        case PERMISSION_DENIED:
            System.err.println("Error: Permission denied to read file.");
            break;
        case READ_ERROR:
            System.err.println("Error: Failed to read file.");
            break;
        default:
            System.err.println("An unknown error occurred.");
    }
}

Resultオブジェクトとエラーを表すenumを組み合わせることで、メソッドの戻り値から「処理が成功したか、失敗したか、そして失敗した場合はその具体的な理由」という意図が明確に伝わります。呼び出し元はisSuccess()やisFailure()で状態を確認し、失敗時にはgetError()で詳細なエラー情報を取得できます。このアプローチは、特に複数の種類の失敗が起こりうる操作において、エラーの意図を統一的かつ詳細に伝えるのに有効です。

例外と戻り値の使い分けにおける意図

例外と戻り値のどちらを選ぶかは、発生する状況が「例外的な事態」なのか、それとも「ありうる結果の一つ」なのかという観点から判断すると、コードの意図をより正確に伝えることができます。

例えば、「ユーザーが存在しない」という状況が、そのメソッドの仕様上「ありうる結果」（例: 検索機能）であればOptionalやResultオブジェクトが適しています。一方、「存在しないはずのユーザーIDが指定された」（例: 削除機能など、事前に存在確認が済んでいるべきコンテキスト）場合は、それは「例外的な事態」とみなし、例外をスローする方が意図が明確になることがあります。

エラー処理のアンチパターンと意図の不明瞭さ

コードの意図を不明瞭にするエラー処理のアンチパターンとしては、以下のようなものがあります。

これらのアンチパターンを避け、なぜそのエラー処理が必要なのか、どのようなエラーを想定しているのか、エラー発生時には何が期待されるのかといった意図を意識することが重要です。

まとめ

エラーハンドリングは、コードの堅牢性を確保するだけでなく、設計者の意図をコードを通じて効果的に伝えるための重要な側面です。例外は「例外的な状況からの脱出」という意図を、戻り値（特にOptionalやResultオブジェクト）は「ありうる結果としての成否や詳細」という意図を伝えるのに適しています。

コードレビューで「なぜここでこのエラー処理をしているのか？」と問われたり、他者の書いたエラー処理の意図が掴めずに困ったりした経験がある方もいらっしゃるかと思います。本記事で紹介したように、例外の選択、情報の付加、戻り値の形式などを工夫することで、エラー処理の背後にある設計者の意図をコード自体に語らせることが可能です。

エラーハンドリングのコードを書く際には、単に動く実装を目指すだけでなく、「このコードを読む人に、どのような状況でどんな問題が起こりうるか、そしてそれに対してどう対処してほしいか」という意図が明確に伝わるか、ぜひ意識してみてください。それが、あなた自身の、そしてチーム全体のコード品質を高める一歩となるはずです。