初心者の頃に知りたかった「何か動かない」を解決するコツ　～何を読むか編～

この記事は [ラクス Advent Calendar 2020](https://qiita.com/advent-calendar/2020/rakus) の1日目の記事です。
アドベントカレンダーの季節だけ Qiita の記事を書くことがそろそろ恒例になりつつあります。
初日からコケるわけにはいかないので今年も筆を執りました。

私の所属は子会社の [ラクスパートナーズ](https://www.rakus-partners.co.jp/) です。
今年の春から社内の職種分類上は『機械学習エンジニア』に転生して数学や統計学もちょこちょこ勉強しています。
ただ、普段の仕事は相変わらず『[データアーキテクト](https://speakerdeck.com/shinu/maemuki-data-seibinin01?slide=46)』と呼ばれているようなことをしています。
が、まだ浸透していない言葉なので『[データエンジニア](https://speakerdeck.com/shinu/maemuki-data-seibinin01?slide=44)』を自称しています。実際エンジニア寄りの仕事も多いですし。

データエンジニアという仕事の性質上、扱うプログラムはバッチ処理などの裏方です。
web アプリのようなプログラムとは違って実行結果がすぐに画面で確認できるわけではないのでデバッグには少しコツが必要です。
同じような内容の記事は探せばたくさん出てくるのですが、ヒットする経路が増えることはそれはそれで意味があると思うので改めて書いておきます。

今回はプログラムが「何か動かない」状態に陥ったときに何を読んで解決しているかをまとめてみようと思います。
「何を読むか」以外に「原因をどう絞りこんでいくか」とかもあるのですが長くなりそうなのでまたの機会があれば。
思いつきで書いたので抜け漏れを後で追加する可能性があります。（ストックしておいてネ！）

# 読んだ方が良いもの
個人的にはこれらを読めば8割前後くらいの問題は解決する気がしています。

## エラーメッセージ
とにかくまず読む。
のだが、初心者に限ってなぜかこれを読まない。
多分パッと見何が書いてあるかわからないからだと思います。

確かに大抵数十行くらいエラーメッセージが出るので読みたくない気持ちはわかります。
が、ぶっちゃけ数十行全部読む必要は無くて

* 例外の種類
* 例外の原因
* 自分の書いたプログラムの何行目か

くらいを読めば OK です。

職場の先輩に質問する際もこのエラーメッセージを全文お伝えしてあげるとその後のコミュニケーションがスムーズです。
思考力を鍛える訓練として自分で原因を考察してみるのは良いのですが、大抵の考察は的の斜め下辺りを射貫くのでまずはエラーメッセージを渡してから考察をお伝えしましょう。

## 公式ドキュメント
使っているライブラリ・ミドルウェアが例外の原因だとわかったら公式ドキュメントの該当箇所を読みましょう。
公式ドキュメントは英語の場合が多いのでちょっとハードルが高いのですが結果的に一番早く解決できることが多いです。
最近だと DeepL など機械翻訳の精度もだいぶ上がってきたので意味を掴むのも簡単になってきたと思います。

* どんな状況になると例外が発生するか
* 各例外は何を意味しているか
* 解決するために必要なこと
* サンプルコード・設定例

などが書かれていることが多いです。
日本語のブログ記事などで解決できることも多いのですが、微妙に内容が間違っていることが多いので自分で情報の補正ができるようになるまでは頼りすぎない方が良いです。
企業ブログはさすがに間違いは少ないですが個人ブログは本当に玉石混交……。

## GitHub 等の issue
OSS であれば GitHub 等の issue で今陥っている状況と同じことが書かれている場合があります。
中には『次期リリースで解消されるけれど急ぐならこれで対応してね』と言った内容もあって意外と役に立つことが多いです。

プログラムの作者やコントリビューターが回答している内容であれば特に信頼できます。

## Stack Overflow の緑のチェックマークのある投稿
エラーメッセージをググるとよくたどり着く [Stack Overflow](https://stackoverflow.com/) もオススメです。
緑のチェックマークが付いていて vote が 10 以上の投稿は結構信頼できます。

解決済みの回答の多くは

* 何故この問題が起こっているか
* プログラム内でどんな処理が行われているか

などの解説も一緒に書かれていることが多いのでありがたく読ませていただきましょう。

## 実行中のプログラムの変数の中身
ここからは自分で読むものを獲得していきます。

* IDE やテキストエディタのデバッガを使う
* print 関数やロガーで標準出力に出るようにしてプログラムを実行する

など方法は色々ありますが実行中のプログラムの変数の中身を見てみるのは覿面に効きます。
変数の型、実際に入っている値が想定と違えばそこから何故そうなったのかを手繰っていけます。

## 適切に出力したログ
データエンジニアにとってログは障害発生時に自分を助けてくれます。
ただ、その割に私はログ設計を結構勘でやってしまっているので明確な指針をうまくお伝えできません……。
ザックリとした指針としては『障害が起こったときに知りたいことを出しておく』のがコツかなと思います。

* どのファイル、どのレコードを処理したときに障害が起こったかが分かる主キーになる情報
* 主キー以外に知っておきたい変数
* SQL などのクエリで発生した例外の場合は発行したクエリ

などを出力することが多いです。

参考：https://qiita.com/nanasess/items/350e59b29cceb2f122b3

# 読まない方が良いかもしれないもの
解決できるかもしれないけれど余計深い沼に沈むかもしれない情報たち。

## 古い記事
Stack Overflow などを読む際は投稿された日付やバージョンに気をつけましょう。
十分に枯れたプログラムの記事ならいざ知らず、開発が活発な OSS などは投稿から一年経つと全然別物になっていることがそこそこあります。
最新版では非推奨になった方法やそもそも最新版で削除されている機能というケースを踏む可能性が考えられます。
とは言えどんな設定ができるかのヒントになることも結構にあるので全く役に立たないわけではありません。

## どこの誰が書いたかわからないブログ記事
Qiita に記事を投稿しておいてブーメランな気はしますが、Qiita に投稿する記事を書くときに実際に手を動かして確認しながら記事を書くことって少ない気がします。
一通り作業し終わってからやったことを思い出しながら書くことが多いと思いませんか？　人間の記憶は結構いい加減なもので思い出しながら書くと数カ所くらい間違いが混ざることがあります。
ただ、大筋は正しいことが書かれているのでこちらも全く役に立たないわけではありません。

# まとめ
* 障害対応するときは信頼できる情報源にあたりましょう！
* 信頼できる情報源は大抵英語です！　でも DeepL 使えば結構何とかなる！

以上です。
他にも「こんなの読むと良い（良かった）です」などあればコメント欄に残しておいていただけると！

明日も誰かが記事を投下してくれることでしょう！