現場で役立つ資料の小技

前提

書いている人

都内某社でSESとして働いています。
現在の出向先は一部上場企業の二次受け。
主な業務はクラウドの提案と構築。
ただ時間が余ってるので、社内ツールの作成から、バックフロント両方のタスクを遊撃的に片づけています。

書いた理由

プログラミングそのものや、それを学ぶための技術、局地的な解決方法なんかはqiitaなどでも積極に記事としてノウハウがあります。
こうした知識のオープンソース化は非常に良い文化だと思うので、積極的に投稿・活用させてもらっています。
しかし、個人的にはもう少し足りないなという思いがあります。

プログラマーの主な仕事は、設計とかコーディング、テストです。
しかし、成果を上げてお金をもらうためには、仕様や設計以前の「要求定義に関するノウハウ」の共有なども重要ですし、
それを「どのようにドキュメント化して、クライアントとエンジニアが健全で豊かな関係を作るか」という部分は非常に高いニーズがあると思っています。

例えば僕は今の現場で「とりあえずお客さんはエクセルで検討したいらしくてね」という上司さんの言葉でエクセル職人をやっています。
たしかにエクセルは良いソフトですが、そのエクセルの上で「おえかき」したり、手打ちで「決定印がおされた書類をエクセルに打ち込む」とか、果てはエクセル方眼紙をパースするとか。
そういう悲しい事態を、どうにかしていきたいなと思うわけです。

そこで、とりあえず自分のノウハウがある範囲で、要求定義レベルから使える資料周りの小技について書いていくことにしました。
なお、内容がほぼポエムなのは理解しているため、後日撤去する予定です。

概要

本文

ドキュメント用ライブラリを提案しよう

クライアントとのお話をする場所に自分や上司が立てるなら、「エクセルにこだわらない（最も効率的なツール・ライブラリを使う）」という部分を押し出しましょう。
大きな会社さんほど「とりあえずビール」もとい「とりあえずエクセル」と言っていますが、彼らが欲しいのは注文内容を検討するための資料であり、それを簡単に正しく読み取れるフォーマット付きのデータってだけです。
エクセルは集計・数値計算が必要な場面では十分な能力がありますが、例えば「図解」するような場面で効率的なツールではありません。
GraphvizやPlantUML、Mermaidなど、スクリプトから設計など可視化するツールはたくさんあるので、エンジニアがエクセル方眼紙にお絵かきする無駄を省いて、その分を「お安くする」なり「デザイナーにちゃんとした資料として絵にしてもらう」なりしましょう。

ドキュメントのバージョン管理を徹底させよう

バージョン管理をしていないドキュメントは、チームの機動力・安全性・心理的余裕を殺しますし、なにより時間とコストの無駄が増えます。
ちょうどうちのプロジェクトでも、パーサーを書いたばっかりのエクセルファイルの構造を（パーサーが事故らないようにローカルで作業してたら）他の人が構造ごと変えるという事故がありました。
「そんなに規模の大きなプロジェクトじゃないし」
「わざわざバージョン管理なんて」
という上司がいたら、泣き落としてもなんでもいいので、バージョン管理を徹底しましょう。

あなたは、自分が書いた一日分の仕事を、上司の気まぐれで上書きされたうえで「君は仕事ができないな」と言われて、笑顔でいられますか。。。。？

エクセル資料は生成しよう

だいたい「エクセルで資料頼むよ」と言われた場合、普通にエクセルを開いて作業し始めるかと思いますが、ちょっと後にしましょう。
YamlなりJsonなり、XMLでも構いません、データそのものはモデリングランゲージやオブジェクトランゲージで書き起こしていきましょう。
そのうえで、適当なCLIツールを使ってエクセルなどにそのデータを流し込んで上司に渡せるようにするべきです。
上でも書きましたが、エクセルはわりと容易にデータ構造（行列の位置関係」などを動かせてしまいますし、縦横二次元でデータを表すため、データ内容の検討に十分な思考的余白を用意できません。
そのため、設計にかかわるデータ本体と、一種のビュー（可視化ツール・フロントエンド）としてのエクセル等のファイルを切り分けて、「設計データ⇒見せるデータ」で生成するようにしましょう。
また、こうすることで、バージョン管理も含めた保守・改良を行いやすくなり、最終的には時間と手間の節約にもなります。

ちなみに、僕は使い慣れているのでnpmを使ったCLIをたたいて作業しますが、別に納品するわけではないので、作業さえできればなんでもいいと思います。
.Netのライブラリにアクセスできるなら、あなたが使いたい言語やアーキテクチャなどを、比較的低リスクで実務に生かせるチャンスになると思います。

上司に見張られている場合

とはいえ、エクセル資料を作ってくれと言われた作業者がエクセルを開いていなかったらにらまれることしきりです。
そういうときの為に、画面の半分は「どこにどんな色や罫線で可視化するかの検討をしています」というポーズは忘れないようにしましょう。
もちろん、こうした作業をすることで「最終的には得なので」といっても、必要な期日に必要な作業が間に合ってなかったらアウトなのは間違いないので、自信がなければ最初はもうエクセル職人仕事を割り切るのも一手です。
見張られている以上は集中してプログラミングもできないと思うので、そういうときは気持ちを切り替えて人間ロボットになりましょう。。。。

エクセルデータが先にある場合

エクセルからデータを読み出して、特定のあれこれを作ってほしいといわれることもあります。
上記した「データファイル⇒可視化のためのエクセルファイル」だったら、データファイルが本体なので、簡単な読み取りで作業できますが、エクセルからとなるといろいろ事故も起きますし、手間もかかります。

そういう状態になったとき、いくつか知っていると作業が楽になる小技があります。

コンフィグ・辞書ファイルを作る

読み込み元のエクセルを渡された場合、それをそのままパースしようとするのは悪手です。
そういうファイルは「手作業で作られている」ものが多いので破綻や例外が多く、正面から挑むと「半自動」にしかできません。

その対応として、まずは定数として扱う各種コンフィグ・辞書を作成しましょう。
例えばファイルを読み込むためのファイルをリスト化し、その内部で頻繁に使われているデータや語彙をまとめておくだけでも、エクセルを解釈するのはずいぶん楽になります。

目次をつくろう

内容が少ない場合でも、目次ページを作っておきましょう。
内容を変更して大丈夫ならシートの中に「目次」ページを。
そうでないなら、ファイル軍の管理用としての辞書ファイル内部に、ファイルごとに書いていきましょう。

もう「あとは絶対にファイルの中身を更新しない」ような状態であればやらなくてもいいですが、後から更新される可能性があるなら、「パーサーがそれぞれのデータを読んでいくための確固たる足場」となる部分があるかどうかで、パーサーの書きやすさが大きく変わります。

空間は広めにとろう

また、そうした「目次」などは普通のマトリクス（縦横の表）になるとおもいますが、
こうした表を作る立場にいる場合は、できるだけ「余裕をもって広めに作る」ことをお勧めします。
ビューとして使っているエクセルに対する機械処理では、わりと縦横の位置を変えられてしまいますし、
実験的なプロジェクトなら、進行中に新しく項目が増えるという事態もそう珍しくありません。
そういうときに、「一覧」「目次」「リスト」などの部分で余裕をもっておくと、パーサーでの対応が非常に楽になります。
細かい部分ですが、作業効率が変わるので「余裕が大事」は覚えておくとよいかと思います。

長さの文化

あと、これは出身文化で「いわれるまでもないよ」ということも多いですが、一応。
Range関数やfor文に対して、プログラミングでは二つの解釈が主流になっています。

一つは「始まりの場所と終わりの場所を使って計算する」というもの。
こちらは「０から始めて、イテレータが１０を見たら終わり」みたいに解釈します。

もう一つは「（始まりの場所と）対象の長さを使って計算する」というものです。
こちらは「数値を３つ読み取って」のように使います。

上記のようなエクセル設定表などでは、項目数とデータがセットになっていることがおおいため、パーサーの設計時には後者のように「長さベース」で読み取り処理を書くようにしておくと非常にはかどるかと思います。

エクセルパースでざっくり使いたい

これは本当に蛇足ですが、
自分がパーサーを使ってて割と「作ってよかった」と思った機能について。

一つはコメントアウト機能
特定のデータについて、「今回は実験環境だから、このデータはつかいたくない」とか言われる事があったりすると思います。
そういうときに、パーサーそのものや、パースしたデータを再加工するなどは非常に面倒な作業です。
というわけで「セルを読み取ったとき、最初に//がついていたらNullとして読む」とか「ひとつとなりを読む」とか、
ちょっとした、一時的な変化に対応するための機能が用意できているといいかなと思います。

二つ目はファイル分割・マージ機能
一つの設定ファイルを渡されても、それをもとに出力するファイルが一つとは限りません。
というか、AWSのCloudformationなんかは一度に流し込める設定の数に上限があるため、うっかりしているとパーサーそのものの設計から見直したりしなくてはいけなくなります。なりかけました。
もちろん、複数の設定ファイルを渡されて、いい感じに一つのファイルとして出力してよと言われることもあります。
このあたり、わりと後半に「ちょっとやってよ」と投げつけられて死んじゃう系のアクシデントなので、こういう事態があることを前提に、アーキテクチャを考えましょう。
やりすぎは禁物ですが、たまによく発生する事態には備えておくとよいかなと。

あとがき

というわけで、最近ちょっと感じたこと、思った事をざくざく書きました。
また近いうちに、今度はCloudformationまわりとかでも似たようなあれこれを書きたいと思います。

なお、最初に書いていますが、この記事はQiitaの趣旨とは少し違う気がするので、いずれどこかに移動させる予定です。
しかし、それまでにご意見・アドバイスなどいただけると大変たすかりますし、肩をぽんぽん、ってたたいてくれるだけでも励まされるので、優しくお願いします。

みなさんのエンジニア生活から、少しでも苦しみが減りますように。。。。