logo サブスレッド

開発ポリシー

こんにちは女子大生です。 年1回ブログを書くという目標を早々に達成しましたv

ところで我々の目標はよりよいものを納品することであり、そのためには品質の高いプロダクトを開発する必要があります。
今回はそんな観点で開発時に気をつけるべきことを書き残しておきたいと思います。

変更履歴を尊重する

基本的にバージョン管理システムというやつはファイルの変更差分を記録します。 これを精査することでそのコミットがどんな変更をしたものかを明確にすることができるわけです。 一度に大量の変更がコミットされると変更内容がわかりにくくなるのでより細かい粒度でコミットする、、という原則があります。 変更差分が大きい(多い)とレビューも大変で、うっかり必要のない変更までコミットしてしまうかもしれません。 意図しないコードの修正をコミットしてしまうかもしれないのです。 例えばどこかの数字をうっかり1文字(一桁)消してしまったとして、大量の差分の中からそのうっかりを見つけられるか?みたいな。

つまり、 余分な差分は邪魔 ということです。ひとつのコミットにはそのコミットで必要な最低限の差分だけがあるのが望ましいのです。 しかしそれを維持するためにコミットする度に気を張るのは疲れてしまいます。使えるものは有効に使って手間を減らしたい。

環境固有の設定

例えばエディタ(統合環境)のテンポラリなファイル(.idea/ とか)には環境固有のパス情報などが含まれていたりして、 開発環境ごとに異なるし、意識しないうちに更新されていたりします。 これが都度都度変更差分として記録される必要はなくて、なのでこういうファイルは無視ファイル(.gitignore)になっているはず。

それと同じように、環境固有の設定値も無視ファイルにするべきです。 本番と開発とでURLが異なるとか、ディレクトリパスを書いた .ini ファイルを用意しないといけないとか、etc… 自動的に適切なURLやパスが用いられるのがベスト、という原則を踏まえて、 ローカル環境で動かすとき固有の設定とか、一人一人違う開発環境固有の値なんかは 設定ファイルとしてソースから分離して無視ファイルにするのが望ましいです。 (設定ファイルがなくてもデフォルト値で動作するとよりよい)
以前書いた Django settings.py の話も環境固有の設定値をリポジトリにコミットしない方略のひとつです。

認証に用いる Token や Credential、パスワード等をリポジトリに保存するか否かは プロジェクトごとの機密性等を鑑みてポリシーがあると思いますが、 これも可能なら無視ファイルにしたほうがよいかなーと思います。

プロジェクト内共通のコードフォーマット

ソースがきれいになると可読性が上がってバグを見つけやすくなり品質向上につながります、、という話ではなくて。
チームメンバー(そのプロジェクトに関わるすべての人)で統一したひとつのコードフォーマットを用いることで、 統合環境による自動整形に頼ることができます。 これがもし開発者によって用いるフォーマットが異なるとか、コード整形をしない人がいると、 複数人で同じファイルを交互に編集するときなんかにいちいち差分が出てしまいます。

統合環境でファイル保存時に自動的にコードフォーマットする設定を有効にするとか、 コミット前にコードフォーマットを習慣化するとか、 何かしら統一されたフォーマットでコードが整形されている状態を保つことで不要な差分を減らすことができます。
(その前提としてメンバー全員で同じ系列の統合環境を使う、という必要もあるかもしれません)

中間ファイル・生成物

Windowsアプリの開発をしていて、ソースの修正をコミットする度に実行バイナリ(.exe)もコミットするかというと No だと思います。そもそも実行バイナリをコミットする必要があるかという議論もあります(ケースバイケースな気がする)。

じゃあ TypeScript で生成された .js は? SASS/SCSS の .css や .map は?
原則、コミットする必要はないと思います。プロジェクトによるけどコミットするべきでない。 よっぽど生成される .js .css を使ってチェックアウト(git clone)したそのままの状態で Webページを表示する的な使い方をするのでなければ、手元でコンパイルするべきなのかなと。
コンパイラのバージョンが変わって出力されるファイルに差異が出るかもしれないし、 minify してたら行単位でもすごい量の差分になってしまったりします。

こういった小ワザも駆使して不要な・不用意な変更履歴(変更差分)を出さないことで 「本当に必要な変更箇所」だけをコミットしていくことができ、 レビューが容易になりバグを減らすことができるだろうと思います。

Warningを残さない

エラーと違って Warning(ワーニング)は残っていてもある程度意図通り動いてくれたりします。
でもだからって何十件もの大量のワーニングを放置していいのかと言うとそうじゃない。 そもそもワーニングは文字通り「警告」なのであって、それ自体を直したほうがいいということもあるけれど、 大量のワーニングは見る気をなくさせます。 そして本当に着目すべき重大なワーニングやエラーに気付かなくなってしまう。 直せるものは直すべきです。そのほうがエレガント。

統合環境の警告も同様です。JavaScript や TypeScript は行末セミコロンがなくても動くけれど、 それがないとバグになりかねないし、なにより不格好。 コードフォーマットにもつながるけれど、“自然な” コードのほうがちょっとした不自然や違和感に気付きやすく バグを見つけやすいのです。

ワーニングを取るために何時間もかけることはスケジュールが許さないかもしれないけれど、 新しいプロジェクトを始めるときは最初からワーニングを出さないように書いていきましょう。

ゴミを残さない

試験実装したコードとか、改修前のコードとかコメントとか。使わなくなった変数とか関数とかファイルとか。
いる?それいる? というものが残っているとコード理解を無駄に難しくします。 リファクタリングもしづらい。 使ってると思った変数を参照して動かないことに悩んだり、 意図しない(本当はもう使われない)関数を呼んでエンバグしたり。 使わなくなったコードは百害あって一利なし。 そういうものはバージョン管理システムがちゃんと残しておいてくれるから、 現行ソースからはさっくり消してしまいましょう。


まだまだほかにもあると思いますが、まずはこんな小さなところから始めていけるといいのかなって。
ミス(バグ)を混入しづらくすることで気をつけないといけないところに注力できるので開発効率も上がります。 自分だけでなくみんなのためにぜひ!!

現在の位置:サブスレッド ホーム > 技術ブログ > 開発ポリシー