🎓

【新卒研修】なぜマジックナンバーをやめるのか？なぜconfigにまとめるのか？なぜsecretsに隠すのか？

に公開
Git
研修
新入社員
データ
コード
tech

新卒のコードレビューをしていると、よく次のような課題に出会います。

  • あっさりマジックナンバーを使う
  • パスワードやAPIキーが普通にコードに書いてある
  • GitにCSVファイルをそのままコミットする
  • （特に機械学習系で）hyperparameterがコードのあちこちに散らばっている

でも実は、これらはバラバラの問題ではありません。
すべて同じ原因に帰着します。

それは、

システムの本質を理解していないこと

です。

システムの本質は「データ」と「ロジック」

システムとは何でしょうか？

答えはシンプルです。

システム = データ × ロジック

データ：システムが扱う情報や値

ロジック：データを処理する方法やルール

これだけです。
難しく考える必要はありません。

① マジックナンバーを使ってはいけない理由

例えばこんなコードがあったとします。

if score > 0.8:
    print("OK")

この 0.8 は何でしょうか？

合格ライン？

精度の閾値？

実験的に決めた値？

これは データ です。
しかし今、このデータは ロジックの中に埋め込まれています。

つまり、

データとロジックが分離されていない状態です。

正しくはこうです。

THRESHOLD = 0.8

if score > THRESHOLD:
    print("OK")

こうすると何が起きるか？

  • 意味が明確になる
  • 値を変更しやすい
  • 実験しやすい
  • 再利用しやすい

これは「可読性」の話ではありません。

データとロジックを分離しているだけです。

② hyperparameterを上にまとめる理由

機械学習コードでよく見る例：

model = RandomForestClassifier(
    n_estimators=100,
    max_depth=5,
    random_state=42
)

これがファイルの途中に突然出てくる。

これも同じ問題です。

  • n_estimators
  • max_depth
  • random_state

これらはすべて データ です。

モデルのアルゴリズム（ロジック）ではありません。

だから正しくはこうです。

CONFIG = {
    "n_estimators": 100,
    "max_depth": 5,
    "random_state": 42
}

model = RandomForestClassifier(**CONFIG)

これにより、

  • 実験管理ができる
  • 再現性が保てる
  • 設定変更が容易になる

なぜ？

データとロジックが分離されたからです。

③ パスワードをsecretsに隠す理由

これも本質は同じです。

password = "my_password_123"

これは「セキュリティが甘い」という以前に、

ロジックの中にデータを埋め込んでいる

のが問題です。

パスワードは「環境に依存するデータ」です。

開発環境、本番環境、テスト環境すべて異なります。

つまり、ロジックとは独立しているべきデータ

なのです。

だから .env や secrets manager に入れる。

セキュリティは結果であって、
本質は「分離」です。

④ なぜGitにCSVを上げてはいけないのか？

これも同じ話です。

Gitとは何か？

Gitは「ロジック」を管理する場所です。

コードとは何か？

データを処理するルール。

ではCSVは？

データそのもの。

Gitは差分管理、履歴管理、ブランチ管理

をします。

これは「ロジック」に最適化された仕組みです。

データを入れるとどうなるか？

  • リポジトリが肥大化する
  • 差分が意味を持たない
  • 再現性が崩れる
  • 管理不能になる

なぜ起きる？

データとロジックの区別がついていないからです。

すべては「責務の分離」の問題

まとめます。

問題 本質的な原因
マジックナンバー データがロジックに埋まっている
hyperparameter散乱 設定データが分離されていない
パスワード直書き 環境依存データがコードに混ざっている
CSVをGit管理 データとロジックの区別がない

全部同じです。

データとロジックの分離ができていない。

良いエンジニアの思考

コードを書くとき、常に自問してください。

  • これはロジックか？
  • それともデータか？
  • この値は将来変わる可能性があるか？
  • 環境によって変わるか？
  • 実験ごとに変わるか？

「変わる可能性があるもの」は、
ほぼすべて データ です。

そしてデータは、

  • configにまとめる
  • 環境変数に出す
  • secretsに隠す
  • 外部ストレージに置く

べきです。

研修で一番伝えたいこと

技術は増え続けます。

Kubernetes

Databricks

Terraform

MLflow

CI/CD

でも本質は変わりません。

システム = データ × ロジック

これを理解している人は、

マジックナンバーを使わない

設定を整理する

secretsを分離する

Gitの役割を理解している

逆にこれを理解していないと、
ツールだけ覚えても本質的に成長しません。

最後に

新卒の皆さんへ。

マジックナンバーを使ったから怒られているのではありません。
パスワードを書いたから怒られているのでもありません。

「システムをどう捉えているか」が問われています。

データとロジックを分けて考える。
それだけで、コードの質は一段上がります。

そしてそれは、
エンジニアとして一段上がるということです。

Discussion