まともに使えるソフトウェアを作るためのチェックリスト
この記事について
ソフトウェア開発に慣れていない人が作ったソフトウェアは動かし方がよく分からないことがたいていです。 致命的なバグが残っていたり、そもそもビルドや実行ができないということも多くあります。 この記事は、そのような状況が改善されればよいなと思って書かれました。
ただし、この記事が対象とするソフトウェアは、主にはユーザの環境でビルドして実行するようなもの (例: プログラミング言語処理系) です。 スマートフォンのアプリや Web ページなどは対象外です。 また、基本的に個人開発の OSS を想定しています。
チェックリスト
このチェックリストをほぼすべて埋めることは、まともに使えるソフトウェアを作るための必要条件です。
ドキュメント
どんなにすごいソフトウェアであっても、使い方が分からないようではユーザの役に立ちません。
- ✔️ できる限り丁寧に書く
- ドキュメントは書きましょう。
- ✔️ エラーメッセージはできる限り丁寧なものを出力する
- ✔️ 日本語だけでなく英語のドキュメントも用意する
- 英語を読める人は多いですが、日本語を読める人は少ないです。
- ✔️ CHANGELOG などのリリースノートを書く
- keepachangelog.com を読んでください。
- Git の commit history はリリースノートではありません。
- ✔️
--help
オプションを用意する- 実行バイナリだけから最低限の使い方が分かるようにしておきましょう。
ビルド
どんなにすごいソフトウェアであっても、そもそも実行できないようではユーザの役に立ちません。
- ✔️ 要求されるコンパイラなど処理系のバージョンを明記する
- nightly でしか動かないのか古い stable でも動くのかなどはドキュメントあるいは設定ファイルに書いておきましょう。
- ✔️ 依存しているライブラリをバージョンも含めて明記する
- 依存しているライブラリの一覧を設定ファイルに書き、一括でインストールできるようにしておきましょう。
- ✔️ ロックファイルを配布する
- ロックファイルがあればほとんど確実にビルドを成功させることができます。ユーザの環境でうまくビルドが通らなかったときの保険になります。
配布
- ✔️ ライセンスを設定する
- ライセンスがないソフトウェアを無断で実行すれば著作権上の問題が発生します。ユーザに法律を犯させないために、ライセンスは必ず設定しましょう。
- ✔️ バージョン番号を振る
- 基本的に Semantic Versioning を使ってください。
- Git の commit hash はバージョン番号ではありません。
- ✔️ Git を使い、また GitHub ないしそれに類するサービスを使う
- バグの検索や報告が簡単にでき、また開発の履歴を簡単に閲覧できるべきです。個人サイトで .zip で配布するなどは避けましょう。
- ✔️ (optional) バイナリを配布する
- ビルドが難しいソフトウェアの場合、ビルド済みのバイナリを直接配布することは有効です。
テスト
どんなにすごいソフトウェアであっても、バグだらけであってはユーザの役に立ちません。
- ✔️ できる限りたくさんテストを書く
- テストがないソフトウェアは常にバグっていると思ってください。
- ✔️ Linux, macOS, Windows のすべてでテストを実行する
- 様々な OS で動くソフトウェアを作るのは難しいため、実際に実行してみてのテストが必要です。
- ✔️ linter を使う
- 明らかなバグを検出することができます。
- 動的型付き言語を使っている場合は型検査器は必ず導入しましょう。
- ✔️ (optional) formatter を使う
- ✔️ CI を設定する
- テストが書かれていてもそれが実行されているとは限らないようでは意味がありません。CI を設定して、テストが必ず実行されるようにしましょう。
セキュリティ
- ✔️ ユーザのパスワードなどはできる限り要求せず保存しない
- ✔️ 信頼できない入力などはきちんとエスケープをする
設計など
- ✔️ 破壊的変更を避ける
- アップデートによって今まで動いていたものが急に動かなくなるのは不快です。できる限り避けましょう。
- ✔️ ユーザのことを考えて技術選択をする
- 「○○を使ってみたかったから」で技術選択をすることは避けましょう。そのような個人的な動機はユーザに利益を与えません。
その他
- ✔️ 文字コードは UTF-8 を使う
- ✔️ 時刻の表現にはタイムゾーンを含める。基本的には ISO 8601 を使う
- ✔️ 改行コードが何であっても動くようにする
- Linux 上で開発をしていると CRLF を用いたファイルを処理できないままであることがよくあります。
- ✔️ パス区切り文字が何であっても動くようにする
- Linux 上で開発をしているとパス区切り文字に
\
を用いる OS 上で実行できないことがよくあります。
- Linux 上で開発をしているとパス区切り文字に
- ✔️ 色覚異常に配慮した色使いをする
- 日本人では男性の 20 人に 1 人は色覚異常を持ちます。そのような人たちが利用できないソフトウェアを作るべきではありません。