CombinedConfigurationのコメントを修正し、全クラスで統一

2026年02月15日 15:46 JST rails/rails

https://github.com/rails/rails/pull/56430

#56404 で導入された CombinedConfiguration 関連クラスのコメントを修正し、3つのクラス間で記述を統一しました。あわせて、nil 値が「キーが存在しない」として扱われる仕様を明示しています。

背景

#56404 では、ENVと暗号化された認証情報を統合的に扱う Rails.app.creds が追加されました。この機能を支える CombinedConfiguration、EncryptedConfiguration、EnvConfiguration の3クラスには、それぞれ微妙に異なる表現でコメントが記述されていました。

本PRは、これらのコメントを見直し、以下の問題を解決しています：

EncryptedConfiguration のコメントが誤って ENV に言及していた（実際には暗号化ファイルを読む）
3クラスで同じメソッドのコメント表現が統一されていなかった
nil 値が KeyError を発生させる仕様がコメントで明示されていなかった

技術的な変更

各クラスの require と option メソッドのコメントが、以下の方針で書き直されました。

コメントの構造化

全クラスで「Given」「Examples」の2段構成に統一されました。Given セクションで前提となる設定例を示し、Examples セクションで実際の呼び出し例と戻り値を示します。

変更前（CombinedConfiguration）:

# Find singular or nested keys across all backends. If no backend holds the key, it raises +KeyError+.
#
# Examples of Rails-configured access:
#
#   require(:db_host)         # => ENV["DB_HOST"] || Rails.app.credentials.require(:db_host)
#   require(:database, :host) # => ENV["DATABASE__HOST"] || Rails.app.credentials.require(:database, :host)

変更後:

# Find singular or nested keys across all backends.
# Raises +KeyError+ if no backend holds the key or if the value is nil.
#
# Given ENV:
#   DATABASE__HOST: "env.example.com"
#
# And credentials:
#   database:
#     host: "creds.example.com"
#   api_key: "secret"
#   api_host: null
#
# Examples:
#   require(:database, :host) # => "env.example.com" (ENV overrides credentials)
#   require(:api_key)         # => "secret" (from credentials)
#   require(:missing)         # => KeyError
#   require(:api_host)        # => KeyError (nil values are treated as missing)

nil値の扱いを明示

全クラスで、nil 値が「キーが存在しない」として扱われる挙動が明記されました。require メソッドは nil に対して KeyError を発生させ、option メソッドは default 値を返します。

# Find singular or nested keys.
# Raises +KeyError+ if not found or nil.
#
# Given configuration:
#   db_port: null
#   database:
#     host: "db.example.com"
#
# Examples:
#   require(:database, :host) # => "db.example.com"
#   require(:missing)         # => KeyError
#   require(:db_port)         # => KeyError (nil values are treated as missing)

EncryptedConfigurationの誤記修正

EncryptedConfiguration のコメントは、誤って ENV.fetch を例示していました。このクラスは暗号化ファイルを読むため、ENVへの言及は削除されています。

変更前:

# Examples:
#
#   require(:db_host)         # => ENV.fetch("DB_HOST")
#   require(:database, :host) # => ENV.fetch("DATABASE__HOST")

変更後:

# Examples:
#   require(:database, :host) # => "db.example.com"
#   require(:missing)         # => KeyError
#   require(:db_port)         # => KeyError (nil values are treated as missing)

設計判断

コメントの統一において、実装の詳細ではなく使用例を示す方針が採用されました。

変更前の CombinedConfiguration のコメントは、内部で複数のバックエンドを順に参照する実装を ENV["DB_HOST"] || Rails.app.credentials.require(:db_host) のように記述していました。変更後は、具体的な設定例（Given）と戻り値（Examples）を示し、どのバックエンドから値が返されるかを括弧内で補足する形になっています。

この変更により、利用者は「どのような順序で検索されるか」という実装詳細ではなく、「この設定でこのメソッドを呼ぶとどうなるか」というシナリオベースで理解できるようになりました。3クラスで同じ構造を採用することで、バックエンドが異なっても一貫したインターフェースであることが明確になっています。

まとめ

本PRは、#56404 で導入された設定統合機能のドキュメント品質を向上させる変更です。コメントの表現を統一し、nil 値の扱いを明示することで、利用者が3つのクラスの違いを理解しやすくなっています。実装の詳細ではなくシナリオで説明する方針は、APIドキュメントの保守性も高めています。