なぜコードの書き方を揃えるのか

一括採点のプログラムを書くとき、私は「書き方のルール」を決めています。 今は1人で開発していますが、将来、他の人と一緒に開発するかもしれない。 そのときのために、「こう書く」と決めておくことが大切です。

なぜ書き方を揃えるのか

学校の書類を考えてみてください。 先生ごとに書き方がバラバラだと、読むのに時間がかかります。 フォーマットが統一されていれば、どの先生の書類もすぐに理解できます。

プログラムも同じです。 書き方がバラバラだと、他の人が読んだとき「これ何だっけ？」と 毎回考えなければなりません。 ルールを決めておけば、誰が書いても同じような見た目になり、 読む人の負担が減ります。

自動で整える仕組み

とはいえ、「ルールを覚えて、毎回気をつけて書く」のは大変です。 そこで、自動で整えてくれる道具を使っています。

これらの道具を使うと、細かいルールを覚えなくても、 ファイルを保存するだけで自動的にルール通りになります。 人間が気をつけるのは、道具では判断できない部分だけです。 以下では、そうした「人間が判断する部分」のルールを紹介します。

名前の付け方

パソコンでファイルを保存するとき、名前をつけますよね。 「書類1.docx」より「2024年度_1学期_成績一覧.docx」の方が、 後で探すときに分かりやすい。 Excelでも、列に「A」「B」「C」と表示されるより、 「氏名」「点数」「順位」とラベルがある方が読みやすいです。

プログラムでも同じです。 プログラムでは、計算結果などのデータを一時的に保存しておく「箱」を使います。 たとえば、「生徒の人数」を計算して、後で使うために取っておきたい。 そのための箱を用意して、名前をつけます。

「cnt」は「count（数）」の略、「num」は「number（数）」の略です。 略し方は人それぞれ。 後からプログラムを読む人は「この箱には何が入っているんだろう？」と 毎回調べなければなりません。

一方、「studentCount（生徒の数）」なら、名前を見ただけで分かります。 だから、名前の付け方にもルールを設けています。

ファイル名を「書類1」ではなく「成績一覧」にするように、 プログラムの中でも分かりやすい名前をつける。 単純なことですが、これがあるとないとで読みやすさが大きく変わります。

使わないコードは消す

プログラムを開発していると、機能を追加したり、 やり方を変えたりすることがよくあります。 たとえば、「採点結果の表示方法を新しくしよう」と思って、 新しいコードを書いたとします。

このとき、前のコードはどうするでしょうか。 「新しい方法がうまくいかなかったら戻せるように」 「参考になるかもしれないから」 と、前のコードを残しておきたくなります。

部屋の整理と同じです。 「いつか使うかも」と取っておいたものが積み重なると、 本当に必要なものが見つけにくくなります。 プログラムでも、使っていないコードが残っていると、 後から読む人が混乱します。

一括採点では、使っていないコードは消すルールにしています。 「後で必要になったら？」と心配する人もいるかもしれませんが、 Gitという道具を使うと、過去のコードはいつでも取り出せます。 削除しても履歴に残っているので、必要になったら復元できます。 だから、今使っていないものは思い切って消しても大丈夫です。

ファイルの置き場所

一括採点は、約650個のファイルで構成されています。 小さなメモ帳アプリなら数個のファイルで済みますが、 採点画面、成績表、PDF出力...と機能が増えるほどファイルも増えます。

650個のファイルがバラバラに置いてあったら、 「あの処理はどこにあるんだっけ？」と探すだけで日が暮れてしまいます。 だから、ファイルをどのフォルダに置くかにもルールを設けています。

例えば、「生徒」のデータは採点画面でも成績表でも使います。 だから共有フォルダに置きます。 一方、「答案をアップロードする処理」は答案管理画面でしか使いません。 だから答案管理画面のフォルダ内に置きます。

本棚と同じです。 よく使う辞書は手の届く場所に、 特定の教科でしか使わない資料はその教科のコーナーに。 ルールを決めておけば、誰でも目的のものを見つけられます。

型を決める

プログラムでは、データの「型」を決めることができます。 型とは、そのデータがどんな形をしているかの定義です。

例えば「生徒」のデータなら、 「名前は文字」「出席番号は数値」「IDは文字」のように、 どんな項目があるか、それぞれ何が入るかをあらかじめ決めておきます。

型を決めておくと、プログラムが間違いをチェックしてくれます。 「出席番号に文字を入れようとしている」 「名前の項目がない」 といったミスを、動かす前に発見できます。

一括採点では、データベース（SQLite）の設計から型を自動生成し、それをプログラム全体で使っています。 同じデータなのに場所によって型が違うと混乱するからです。 詳しくは「データの型を統一する」の記事で解説しています。

コメントと説明書

プログラムには「コメント」を書くことができます。 プログラムの動作には影響せず、人間向けのメモを残せる機能です。

ただ、何でもコメントを書けばいいわけではありません。 先ほど説明した「名前の付け方」のルールを守っていれば、 名前を見るだけで何をしているか分かります。

// ユーザーを取得する    ← このコメントは省略できる
const user = getUser()   ← 「getUser」で分かる

getUserという名前が「ユーザーを取得する」という意味を表しています。 この場合、コメントを書いてもいいですが、省略しても伝わります。

むしろ役立つのは、コードを読んだだけでは分からない情報です。 「なぜそうしているか」という背景や意図は、 コードには書いていないからこそ、コメントで補足すると助かります。

こうした背景情報があると、後から読む人が 「なぜこうなっているのか」を理解しやすくなります。

処理のまとまりには「説明書」を書く

プログラムでは、一連の処理をまとめて名前をつけることができます。 例えば「Excelファイルを書き出す処理」をひとまとめにして、 「exportToExcel」という名前をつける。 こうしておくと、他の場所から「exportToExcel」と書くだけで、 その処理を呼び出せます。

こうした「処理のまとまり」には、説明書を書いておくと便利です。 何をする処理なのか、何を渡せばいいのか、何が返ってくるのか。 一括採点ではJSDocという形式で書いています。

/**
 * プロジェクトの採点データをExcel形式で書き出す
 *
 * @param projectId - 書き出すプロジェクトのID
 * @param options - 書き出しの設定
 * @returns 書き出されたファイルの保存場所
 */
function exportToExcel(projectId, options) { ... }

/**で始まる部分がJSDocです。 この形式で書いておくと、開発ツールが自動で読み取って、 処理を使うときに説明をポップアップで表示してくれます。

一括採点では、他のファイルから呼び出される処理には 必ずJSDocを書くルールにしています。 名前だけでは「何を渡せばいいか」「何が返ってくるか」までは 分からないからです。