（まず追記）
自分たちで新たに作成する仕様書はMarkdownで記述してGitHubで管理しています。
こんなのも書いたくらいだし、そこは犯していないです。GitHubを中心とした開発プロセス ドキュメント管理
この記事内で言う仕様書とは、「エクセルで作られて共有サーバに置いてあるチーム管理外のファイル」を指します。
こーゆーの、良くあるよね？
public class FooService {
/**
* 仕様書：ad.xxx.net/development/lorem/ipsum/dolor/sit/amet/consectetur/adipiscing/elit/sed/do/eiusmod/tempor
* incididunt_2.xlsx
*/
public void apply() {
}
}
見た瞬間「_2.xlsxってなんだよォ...このパス絶対古いんじゃあねェのー？」って思う感じのやつ。
ついでに仕様書のパスが長くって妙なところで改行入ってるおまけ付き。
こんなの見るとイラっとする！
- コピペしづらい
- そのパスに仕様書が実在するかわからん
- 実在するとして、開くのが面倒
- ある1つの仕様書のパスが1箇所にコメントされていたら、あと数カ所はコメントがあると思う
- でもちょっと手入れされてたりで数箇所のコメントが同じ場所を指していないことが往々にしてある
- 仕様書のパスが変わった場合に、ここ以外でもこの仕様書のパスがコメントされている箇所があるかわからん
- 仕様書の名前(
incididunt_2.xlsx)を知らないと、全文検索でそのコメントが既にどこかに書かれているか探すことも出来ない - コメントされている仕様書一覧が存在しないので見通しが悪い
軽い気持ちで書いたただこれだけのコメントにちょっと考えるだけでもこれだけの悪い点が！
文字列のコメントって点が大体の原因では？
なんかいつだったか急に
「コメントで管理とか激ダサだぜ。Enumでも作ってそこにリスト作って、アノテーションでちょっと目印入れれば良くね？」
なんて思いついて作ったのが下で紹介する@DocPathアノテーション。
超シンプル低コストなのでやってみると良いよ！
例によってimport文やコンストラクタは適当に略していくので、書くかlombokでも使ってね！
src
まずはこんな感じでEnumを作って、パスにラベルを付ける感じでバシバシ定義していくよ！
public enum Path {
API設計方針書("foo.ad.xxx.net/development/api/docs/readme.xlsx"),
認証について("foo.ad.xxx.net/development/authentication/docs/about.xlsx"),
DB_会員テーブル("foo.ad.xxx.net/database/tables/users.xlsx"),
DB_購入物テーブル("foo.ad.xxx.net/database/tables/items.xlsx"),
サーバ構成資料("foo.ad.xxx.net/infrastructure/docs/service-A003.xlsx"),
物流システムAPI仕様書("www.xxx.net/development/logistics/api/api.html"),
在庫管理システムAPI仕様書("www.xxx.net/development/warehouse/api/stocks.html");
private final String value;
}
そんでアノテーションを作る！
ホントに作るだけ。マーカーアノテーションって言うの？（違ったらすいません）
public @interface DocPath {
Path path();
String note() default "";
}
これだけじゃ！
使ってみるよー
@DocPath(path = Path.物流システムAPI仕様書)
public class LogisticsService {
public void apply() {
}
}
備考も書ける！
public class StockService {
@DocPath(path = Path.在庫管理システムAPI仕様書, note = "引当についてはシート2")
public void take() {
}
@DocPath(path = Path.在庫管理システムAPI仕様書, note = "戻入についてはシート3")
public void revert() {
}
}
利点
まず、ホントDocPath.javaとPath.javaを作るだけなので超低コスト！
あとは真面目にいくつか。
-
Enumが自分たちが見る仕様書のリストになる - 自分たちのチームで通じやすいラベルが付いてる感じになる（パスは
valueで、ラベルがEnumの要素名って感じ） - ソースから
Enumへのジャンプはもちろん、エディタのFind Usase機能とかを使えばアノテート箇所への逆ジャンプも出来る！ - パスの修正は当然
Enum側一箇所で済む
まぁ一言で言うと、コメントからJavaに昇格したので、エディタの恩恵を受けられる様になるよ！ってことだね。
更に
ここまでで十分使えるレベルだし役に立ちます。
ここから先はおまけで他に工夫するポイントを紹介するよ。
この内のいくつかは必要に応じて今のチームでも実現済みだよ。
アノテーションの体裁を整える
-
@Targetで@DocPathを書ける箇所を明示する -
@Retentionで@DocPathの有効な範囲を明示する
まぁ大抵は前者はクラス定義とメソッド定義、後者はクラスファイルに含めない、で良いと思う
Raw String
Windowsで開発していてパスに\が含まれる場合はRaw Stringを使うと読み書きしやすいと思う。
その場合はPath.javaをPath.groovyにでもすると良い。
API設計方針書(/\\foo.ad.xxx.net\development\api\docs\readme.xlsx/),
見た目を綺麗にしたい
縦を揃えたくなったら、いくつかポイントがある。
public enum Path {
//@formatter:off
API設計方針書 ("foo.ad.xxx.net/development/api/docs/readme.xlsx"),
認証について ("foo.ad.xxx.net/development/authentication/docs/about.xlsx"),
DB_会員テーブル ("foo.ad.xxx.net/database/tables/users.xlsx"),
DB_購入物テーブル("foo.ad.xxx.net/database/tables/items.xlsx"),
//@formatter:on
- 等幅フォントを設定する
- IntelliJでRictyを使うには過去に書いた記事があるので参考にしてください
- 自動フォーマットを無視させる
- 同じくIntelliJでの設定方法はこちらを参考にしてください
（追記）
ずれてる...手元の等幅フォントでは縦揃ってるんだけど、Qiitaのコードシンタックスの中はPフォントなのかな？
リンク切れを検知したい
ぶっちゃけコメントを辞めてJavaにした時点で、その辺はもうどうにでも出来る。
Spockで適当なテストコードとcheck(Path path)メソッドでも書いて
Path.values().each { check(it) }
みたいにしても良いし、Enumを振る舞わせる感じで
:
:
public void check() {
// this.valueをどうにかする
}
でも良い。
開きたい
これもどうとでもなる。
Enumに振る舞わせてReplを使うのが一番簡単かなぁ？
:
:
public void open() {
// this.valueをどうにかする
}
repl> Path.API設計方針書.open()
GroovyかScalaで（まぁJava9ってことはないだろうし）でも動かせるなら、ReplからEnum自体に開けーって言うのが手っ取り早い。
おまけで、Macのopenコマンドについて過去に書いた記事をリンクしておくよ。
要はダブルクリックなので、.xlsxならエクセルが、.htmlならブラウザが開くので、Macなら"open " + this.valueで十分！
他自由
ダウンロードするなりなんなり好きに出来る。
ただファイルの存在チェックとか外部コマンド（openとかcpだかwgetだか）をするなら、Groovyとかの方が楽そうだ。
一応掲載したサンプルコードと適当にチラした小ネタで冒頭に書いた不満点はほぼ解消できているはず。
他の言語だと？
結局はコメントを定数に突っ込んだってだけなので、何の言語でも似たことは出来ると思う。アノテーションになるのかはわからないけど。
ただ列挙型を作って目に付くところに置けば良いので、ある程度似たことは出来るはず。
嘘コメントパスを撲滅すべし！