Murga

個人的に言いたいコト・主張・気持ち。

日本の SE が好きそうな Excel ドキュメントのテンプレートを作った

ニホンノエスイーは Excel が大好きだ。設計書、テスト仕様書、WBS などは、当然 Excel で作る。

ただ、ニホンノエスイーのほとんどはスキルが低く、Excel すら使いこなせない。そのくせリッチな見た目や不必要なレイアウトに凝ったりするので、保守・拡張しづらいゴミみたいな Excel が生まれる。そしてゴミみたいな Excel を渡された他のメンバは、それを編集する気も持てなくなり、結果的にプロジェクトは停滞していく。

コイツらに「Excel なんか止めて、こういうイケてるツール使おうよ!」とか言っても、イケてるツールに移行できるだけのスキルもやる気もない連中なので、脱 Excel は諦めた方が良い。

それに、Excel というツール自体は、そう悪いモノでもないと思っている。誰の PC にも入っているという手軽さもそうだし、他のツールでは表を上手く扱いづらかったりする中で抜群の視認性・一覧性。プログラム (VBA) の実行環境としても優秀だ。適切に使えれば、毛嫌いするほど悪いモノではないのだ。

というワケで、前置きが長くなったが、どうせ Excel でドキュメント作るんだったらこう作ろうよ、というオレオレテンプレート集を作ってみたので、紹介する。

GitHub で配布しています

作成した Excel テンプレートは以下の GitHub で配布している。ご利用はご自由にドウゾ。加工・編集もお好きに。

github.com

ベストプラクティス・バッドノウハウも公開中

Excel でドキュメント作るならこうするべき、これは避けるべき、というノウハウも、上の GitHub リポジトリの「Wiki」で公開しているので、コチラもドウゾ。

github.com

作成したテンプレート

現時点で公開している、作成したテンプレートは以下のとおり。

  • プロジェクト管理全般で使えそうなモノ
    • 工程定義・マスタスケジュール.xlsx
    • WBS.xlsx
    • 課題一覧.xlsx
  • 上流工程
    • 要件一覧.xlsx
    • 成果物一覧.xlsx
  • テスト工程
    • テスト一覧.xlsx
    • テスト仕様書.xlsx
    • 不具合一覧.xlsx
    • 不具合管理票.xlsx
  • 成果物に対するレビュー管理
    • レビュー一覧.xlsx
    • レビュー管理票.xlsx
  • 本番作業系
    • 作業手順書.xlsx

思想・こだわったポイント

オレオレテンプレートを作る上で考えたことなどを雑多にまとめてみる。ほとんどは「Wiki」にも書いた「定石」に沿ったモノだ。

  • 見た目をリッチにしようとしない
    • 罫線は実線しか使わない
    • フォントは「メイリオ」のみ
  • アラインメントを注意する
    • 全体は垂直上揃えがデフォルト
    • 水平揃えは左がデフォルトで、数値は右揃え。強制的な水平揃えはほとんど利用しない。日付など、入力値の桁数が固定のモノは中央揃えにする場合もある
    • 見出し行は水平・垂直ともに中央揃えにする
    • 日付や数値はゼロ・パディングするよう書式を設定し、「1月1日」と「10月10日」とでアラインメントがズレないようにする
  • メンテしやすい作りにする
    • 行番号 (「No」) 列は ROW() 関数ではなく、行追加などにも対応できる関数を使った
    • 数式で自動入力されるセルは、黄緑の背景色を付けることで「数式が入力されている」と分かりやすくした
    • ハイパーリンクは HYPERLINK() 関数を使うことで「リンクの更新」などが行われないように避ける
    • 見出し行以外では極力「セル結合」を使わない
    • 条件付き書式は避ける : 条件付き書式自体が破損しやすいのと、スタイルだけで意味を伝えようとしないようにするため
  • 全体で統一感を持たせる
    • シート名と A1 セルの見出しは同じ文言にする
    • A1 セルのシート見出しは、メイリオフォントのまま、サイズをデフォルトの10ポイントから12ポイントに上げて太字にするだけ
    • 見出し行は中央揃えで太字、青色の背景
    • 「No」列は必ず設ける
    • 関数で自動入力するセルは黄緑色の背景
    • …というような作りを、どのブックでも同じように行う

…こんな感じ。

  • 最初に作る時に時間をかけないこと
  • メンテナンスする時に執筆規則が読み取りやすいこと

を重視した感じ。

結局、伝えないといけないのは内容であって、体裁に必要以上に時間をかけないことが大事だと思う。

稼げるSEになるための 仕様書 ・提案書作成入門[Word活用編]

稼げるSEになるための 仕様書 ・提案書作成入門[Word活用編]

Excelによるドキュメント作成術―もっとも欲しかった技術者のためのパソコン活用法

Excelによるドキュメント作成術―もっとも欲しかった技術者のためのパソコン活用法

↑なんやこの本は。

単一行コメント記号の直後にスペースを付けないのは「コメントアウトされたコード」を示す

プログラミングにおいて、単一行コメントを書く時は、言語に応じて記号文字は違えど、

# コメントです (Python など)
// コメントです (Java など)

こんな風に、#//記号の直後にスペースを置いて書くことがほとんどだろう。汚いコードを書く人達は、時に記号の直後にスペースを書かなかったりするが、世の一般的なコードは記号の直後にスペースが入っている。

しかし、世の一般的なコードの中でも、記号の直後にスペースを書かない場合があることに気付いた。

例えば、Apache の設定ファイル httpd.conf の場合。

  • httpd.conf
#
# Dynamic Shared Object (DSO) Support
#
# To be able to use the functionality of a module which was built as a DSO you
# have to place corresponding `LoadModule' lines at this location so the
# directives contained in it are actually available _before_ they are used.
# Statically compiled modules (those listed by `httpd -l') do not need
# to be loaded here.
#
# Example:
# LoadModule foo_module modules/mod_foo.so
#
LoadModule authn_file_module libexec/apache2/mod_authn_file.so
#LoadModule authn_dbm_module libexec/apache2/mod_authn_dbm.so
#LoadModule authn_anon_module libexec/apache2/mod_authn_anon.so
#LoadModule authn_dbd_module libexec/apache2/mod_authn_dbd.so

Dynamic Shared Object … から Example までの塊は、人が読むコメントとして書かれているが、その下の LoadModule の行を見ると、

  • #LoadModule

というように、コメントアウトする # 記号の直後にスペースが打たれていない。

次は PHP の設定ファイル php.ini の例。

  • php.ini
;;;;;;;;;;;;;;;;;;;;
; php.ini Options  ;
;;;;;;;;;;;;;;;;;;;;
; Name for user-defined php.ini (.htaccess) files. Default is ".user.ini"
;user_ini.filename = ".user.ini"

; To disable this feature set this option to empty value
;user_ini.filename =

;;;;;;;;;;;;;;;;;;;;
; Language Options ;
;;;;;;;;;;;;;;;;;;;;

; Enable the PHP scripting language engine under Apache.
; http://php.net/engine
engine = On

コチラはコメントアウト記号がセミコロン ; で、最終行の engine = On などはコメントアウトされていないコード。

; Name for user-defined php.ini … という行は、行頭のセミコロンの直後にスペースがあるが、その次の行は

  • ;user_ini.filename = ".user.ini"

という風に、 ;user_ini の間にスペースが開いていない。

コレは何なのだろうか。


最近になって、このスペースが書かれていないコードは、コメントアウトされたコードを示していることに気付いた。

そこで「comment out without space」などでググってみると、次のような Stackoverflow が見つかった。

I've developed software in many languages for about 10 years on projects large and small.
I have yet to see anyone intentionally not use a space.
In the scheme of things it doesn't really matter that much (after all, we all know those are comments and can read them),
but I do think the no-space version looks similar to commented-out code and requires an extra millisecond of brain power to confirm it is a comment :-)

Agreed, spaces for comments, no spaces for commented-out code.

意訳すると、

  • 私は10年間色々なプロジェクトで多くの言語を使ってきた
  • 意図的にスペースを開けないことにしている人は見かけたことがない
  • 結局のところ、人が読めればスペースが開いていようが開いていまいが大した問題ではない
  • ただ、私はスペースを開けずに書かれている場合は、コメントアウトされたコードと認識していて、それが人間用のコメントだった場合は読み取るのに若干の読解コストがかかると感じている

という意見だ。

それに対して

  • 禿同!スペースが付いていたら (人間用の) コメント。スペースなしだったらコメントアウトされたコード。

と返信が付いている。


よくよく php.ini のコードとコメントを見ると、次のように書いてある。

; To disable this feature set this option to empty value
;user_ini.filename =

和訳するとこうだ。

; この機能を無効にするには、このオプションに空の値を設定すれば良い。(次のように)
;user_ini.filename =

つまり、このコメント文と、「コメントアウトされたコード」を参考に、独自に設定したい場合は、「コメントアウトされたコード」のコメント記号を外して、

; この機能を無効にするには、このオプションに空の値を設定すれば良い。(次のように)
user_ini.filename =

このようにコードを有効化してやれば良い、ということだ。


ということで結論。

  • 行頭スペースありのコメント行は、人間が読むためのコメント文を示す
    • 一般的にコメントを書く際は面倒臭がらずスペースを付けよう
  • 行頭スペースなしのコメント行は、コメントアウトされたコードを示す
    • コメントアウト記号を取り外せば、そのままコードとして機能する行になっていることが望ましい

自分は全てのコメントでスペースを付与していたので、「コードとして有効化する場合がある」コメントについては、スペースなしで書くようにしようかなーと思った。

新装版 達人プログラマー 職人から名匠への道

新装版 達人プログラマー 職人から名匠への道

リファクタリング・ウェットウェア ―達人プログラマーの思考法と学習法

リファクタリング・ウェットウェア ―達人プログラマーの思考法と学習法

  • 作者: Andy Hunt,武舎広幸,武舎るみ
  • 出版社/メーカー: オライリージャパン
  • 発売日: 2009/04/27
  • メディア: 単行本(ソフトカバー)
  • 購入: 25人 クリック: 475回
  • この商品を含むブログ (151件) を見る