「仕事のコード」を残す際のチェックリスト
最初に注意: この文章は「はじめに」「総論」が長いです🙃
追記＠2021/08/11 17:46
想像よりはるかに反響をいただいたので、せっかくだからと要点をMarkdownにしてGitHubに置いてみました。何かにご利用ください。
はじめに
・「仕事のコード」、つまり、業務などで作ったコードが、なるべく負債にならず、なるべく俗人化しないようにするために留意すると良さそうなことを自分の経験などから列挙したものです。
・ちなみに、「対象読者」に書いてありますが、そもそものモチベーションが「非エンジニアがノーコード系のサービスで作ったシステムが最近増えつつあるような...」というところでした。こういうのどう取り扱うといいんですかねとなった時、まずは運用できる形にしてもらいたい、という狙いがあります。結果的に、ジュニアなエンジニアが良いシステムを残す上でも使える知識かなと思います。
・個別の項目には異論反論あるだろうというのは前提です。ですが、いったん自分の考えやノウハウをまとめておくのは役に立つだろうと考え公開します。そのつもりでお読みください。
・全体に、雰囲気で書いている箇所もあるため、ご意見、モヤっと感、解釈違い、その他があれば、よろしければ私が気付く形でお伝えいただければ幸甚です。
・そしてもちろん、「こういう項目も必要なのでは？」というご提案があれば教えてください！
対象読者
特に、以下のような方々を対象に、なるべく負債にならない、俗人化しない、お仕事として使ってOKなコードを残すためのノウハウをチェックリスト形式で残しています。
・ジュニアなエンジニアで、ソフトウェアの「運用」の意識を高めたい方。
・非エンジニア。
・CS、営業、Webディレクター他の方々が、何かを自動化したい時に。
なお、本文章では、「エンジニア」はWebあるいは情報システムに関わる、ソフトウェア系のエンジニアを指すこととします。
総論
自動化は良いものです。コードによる改善は良いものです。皆様の業務の生産性を上げる第一歩です。
ですが、ソフトウェアや情報システムは生まれた瞬間に負債化が始まると考えてください。職業エンジニア/プログラマは、この事実に非常に敏感です。構成管理、CI/CDや自動テストなどはこの負債化に立ち向かうために生まれた基本的な技術です。
この文章はエンジニアでない、けどコードでもなんでも使って日々の仕事を自動化したい方々も対象に含まれています。
例えばCS、営業、Webディレクターの方々が、「Google Apps Scriptで何かの業務を自動化しました！」 とシステムをつくったとします。今は、ノーコードやらサーバレスやら、ガチガチな運用の知識がなくとも情報システムを作れるようになりました。
一方で、ここで作られたGASの何かについて、「自動化したんですがうまく動きません！」とエンジニアに渡された場合、大抵のエンジニアは上手く対処することができないでしょう。これは彼らが技術力がないからではありません。ソフトウェアを多くの人が安定して運用するための前提が揃っていないため、そのミスマッチを埋めるのに時間がかかってしまうからです。
そこで、職業エンジニアが、運用も考えてシステムを作る場合、最低限どのようなことを考えているかを残しておくことにしました。
なるべく作ったソフトウェアが長生きし、多くの人を幸せにするために、次のような点を留意いただくと良いのかな？ と思います。
＊ ＊ ＊
チェックリストはここから始まります。
1. 構成管理
・そのコードの動作に必要なものについて、ひとつ残らず何処かに保管してありますか？
・必要なものは、コード自体だけではありません。設定項目、設定に使ったURL、発行したトークン、その他... 必要なものをピックアップして抜き出しましょう。
・そのコードは、Gitにより変更履歴が管理されていますか？
・ファイルホスティングサービスによっては（Dropboxなど）変更管理を機能に持っていまずが、ぶっちゃけエンジニア的に、Git以外のもので変更管理をされても困ってしまいます。
・GitHub EnterpriseやGitlabのようなコードホスティングが社内管理されていれば、そこにpushするのがベストです。
・Gitがわからない、というのはあるかもしれませんが、皆様は非エンジニアであっても、既にコーディングの世界に片足突っ込んでおられます。Gitまでは頑張って覚えるのはいかがでしょう。
・動作に必要なトークンなどは、専用のシークレットマネージャなどに別途保存されていますか？
・トークンがコードの中に混ざっていませんか？
・混ざっている場合、最低でもダミーの表現にして、ドキュメントで「〜を置き換える」などのように書き残してください。
・ドキュメントも残していますか？
・ドキュメントには、本チェックリストの次の項目以降で挙げるような内容を残しましょう。
・ドキュメントは、なんでもいいと言えばいいんですが、一番手軽かつ好まれるのは、プレーンテキストで README.txt というファイルを作成し、一通りの内容を書き残しておき、コードと一緒にGit管理するスタイルです。
・頑張ってMarkdownを覚えられるならそれに越したことはないです（その場合 README.md というファイル名にしましょう）が、Nice to haveというやつです。
2. デプロイメント
・そのコードをどこで動かしているか、書いていますか？
・コードは必ず動かす先の場所が必要です。動かせるようにコードを配備することをデプロイメントと言います。まず、そもそもそのコードはどのサービスで動いているかという情報を残します。
・そのコードを動かすようにするにはどうすればいいか、手順を必要な分だけ残らず残していますか？
・たとえば、GASであれば特定のスプレッドシートに紐づけて保存したりするでしょう。ノーコードサービスの管理画面に入ってコードをコピペして〜のようなパターンもあるかもしれません。
・コマンド一発でできなくても大丈夫です。ですが、必要に応じてちゃんと画面のキャプチャも含めたドキュメントを作りましょう。
・上で「プレーンテキストで」と書いているので矛盾しているように思われるかもですが、優先順位が高いのは「理解できるドキュメント」なので、手順書だけWordで作ってPDFにする（PDFのほうがいいです）という形も始めのうちはいいと思います。
・Markdownの画像挿入の方法などがわかるのであれば、プレーンテキスト＋画像でドキュメントが書けますね。
・動かすために必要な情報は揃って書かれていますか？
・GASが紐づいているスプレッドシートのURLはどれですか？ また、必要な権限は誰に頼んだら得られますか？
・他のサービスを使っていたとして、デプロイしている先のサービスのアカウントはどうやったら作れますか？ 情報システム部門に頼む必要はありますか？ あるいは（あまり良くないですが）共有ユーザですか？
・APIトークンのようなものは必要ですか？ それはどこで保管していますか？ どうやって共有しますか？
・などなど、ざっと思いついたものです。他にもあるかもしれない。
3. 環境とテスト
・そのコードを試しに動かす方法は書かれていますか？
・いわゆる本番環境に影響しない、自由にガチャガチャできるような環境は用意されていますか？ そこにアクセスする方法も、同じように残してください。
・何を書けばいいかわからないときは、例えば最初に試しに動かしてみたときはどういう環境でしたか？ というところから思い出してみましょう。
・このコードは本番でしか動かない、試験時は空気を読んで設定を変えている、などの場合は... その設定の変え方も残してください。
・そのコードが、正しく動いていそうだ、と確認する方法は確立していますか？ そしてそれもドキュメントされていますか？
・そもそもどういう風に動いていることを想定しているか、なるべく細かく残して置きましょう。ちゃんと動いている時の画面キャプチャを残す、などはいい考えだと思います。
・上記のテスト環境で、こういう操作をしたら、こういう出力がされるはずです、という内容を押さえて残して置きます。
・そのコードを動かすための環境はどうやって作りますか？
・必要なソフトウェアをどうインストールするか、必要なアカウントをどうやって発行するか、その他必要な情報にどうたどり着くか、を一通りまとめておきます。
・もし、（素晴らしいことに）そのコードに自動テストが添付されていれば、それを実行する方法も書いておきましょう。
・自動テストがうまく動くコードは、往々にしてテストのための設計になっている必要があり、非エンジニアでは難しいと思います。なので本当に、もしできたなら、という感じです。
4. その他
・そもそもこのコードを作った目的、背景もできるだけ書いておきましょう。
・5W1Hのうち、Whereはデプロイメントの項目、Whatはテストの項目でカバーしました（Whenはおいときます）。そしてWhoはこれから、あなただけ、から同僚みんな、になっていきます。
・残りはHow、Whyですが、Howはコードを見れば大体わかります。頑張れば。How理解の手助けのためにコードにコメントを書くのもいいと思います。
・Whyは、書かないと絶対にわかりません。簡単でいいので目的と作った背景を。引き継ぐ人のモチベーションにもなるでしょう。
・そう、お仕事のシステムは誰かに引き継がれていきます。
・このコードが動かなくなるとどういう人たちに影響が出るか、わかる範囲で書かれていると助かります。
・コード、情報システムの重要性です。エンドユーザにまで影響が出るのか、30分の作業が1時間になるだけなのか、など。
・障害発生時に想定される影響範囲がわかると、変更を加える人がどれくらい慎重に行えばいいかの目安になります。
＊ ＊ ＊
特に非エンジニアの方々には、動くものがあればそれでいい、とも限らないことを覚えていただければと思います。コードの周りにある情報こそが重要です。
・誰でも動かせる
・安定して動かし続けることができる
・継続的に改善できる
職業エンジニアは、こういうソフトウェア・システムに近づける工夫をしています。
重ね重ねになりますが、今回の内容が、少しでもシャドーIT、属人性の高いシステム、そして将来使われなくなり捨てられるソフトウェアを減らしてくれるのなら何よりに思います。
あと、正直、無茶振りをされてストレスがたまるエンジニアも減ると嬉しい。笑
この記事が気に入ったらサポートをしてみませんか？