ノリックのIT生産性向上、ライフハック、プロマネのお仕事備忘録

IT系の仕事の事とか役立つツールとかプロジェクトマネジメントの事とかを記載していきます。

ドキュメントがないシステム再構築案件でソースコードぐらいはきれいにドキュメント化したい

アイデアを思いついた経緯

 今、過去案件のシステム再構築案件に取り組んでいる。当然ながらドキュメントはない。でも大丈夫!!と思ったのもつかの間、前回のプロジェクトでパッケージの仕様は把握出来ているから多少古いバージョンでもなんとか仕様はわかるだろう。と思った自分が浅はかであった。

 まず、他社のパッケージをリプレースした経緯がありもう原型がないほどカスタマイズされている。ドキュメントがない。。帳表イメージがあったがそんなものはシステムを動かせばすぐ分かる話だ。仕方ないのでソースコードとデータベースのデータをにらめっこして、画面を動かしたらどんなふうにデータが更新されるかテーブルイメージを取りつつ、解析をしていく。非常にストレスフルな仕事だ。

 で、PL/SQLをエクセルに貼り付けて、今回のカスタマイズ要件を反映するにはこのステップをこんなふうに直せば要件通りになるはずだからってプログラム仕様書を書いていた。その時思ったんだけど、PL/SQLを見るときはGVIMで見るから、シンタックスハイライトしてくれる。

vim

gvimの画面

それでソースコードをエクセルに貼り付けてカスタマイズする内容や注意点をプログラマーへの指示書として記載している。しかしエクセルに貼ると見栄えが悪い。

excel

同じソースをエクセルに貼った

ソースのシンタックスハイライトははてな記法で逝ける

そういえばソースコードをブログに貼るときにはシンタックスハイライトして貼っているし、同じようにすれば見やすいのではないかと思った。

はてな記法でブログを書く画面を開く。

help.hatenablog.com

 

よく使うから上記ページのリンクとセットにして下書きに私は保存している。

今回はPL/SQLなので小文字でplsql だと宣言する。大文字はだめだ。

 

f:id:norihiko_matsumoto:20190418125518p:plain

はてな記法で反転しているところが言語の宣言

ソースを貼り付けてプレビュー画面にするとシンタックスハイライトされている。

 

f:id:norihiko_matsumoto:20190418125636p:plain

プレビューでシンタックスハイライトされた。

エクセル側での作業

まずはA列を文字列に設定しておく。そうしないとPL/SQLだとコメントのハイフンが計算式にみなされてしまう。

f:id:norihiko_matsumoto:20190418125740p:plain

A列全体を選択して文字列に



あとソースコードにはスペースとかタブが入っていると勝手にデータ分割されることがある。なので一番最初の行に「aaa」とか適当に文字を入れておきデータ区切りの設定を固定長にしておく。

f:id:norihiko_matsumoto:20190418125853p:plain

A列全体の区切り文字を固定長にする

次にエクセルの背景色をはてなプレビューでみた背景色に近いものにしておく。私は濃い青とした。これは人によって使っているテーマが違うから個人の設定に依存する。

A1にカーソルを合せておき、はてなブログのプレビュー画面から貼り付ける。

f:id:norihiko_matsumoto:20190418130226p:plain

プレビュー画面からコピペ

A列の色が取れてしまうのと罫線がついてしまうので、色を再度つけ直し、罫線は邪魔なので取っておく。

 

f:id:norihiko_matsumoto:20190418130317p:plain

完成

ちょっとは設計する時に捗るぐらいに見やすくなったな。実際の仕事では1000ステップ以上あるソースなので見やすさは重要である。

 だが、はてなだとテーマによって色使いが個人個人で違ってしまう。チーム内ではどんな配色にするか統一しておきたいものだ。

 

HackMD/CodiMDをつかってシンタックスハイライト

 よくよく考えたらHackMDでもいいのではと思いついた。自分はローカルPCのDocker環境内で動かしている。それは仕事で使うためセキュリティが問題になる可能性があるためだ。しかしコードハイライトだけだったらログインもせず、文書を保存しなくても良い。MarkDownで「```」と入力して言語の名前を入れれば候補が表示される。

https://hackmd.io/

f:id:norihiko_matsumoto:20190422214747p:plain

HackMD アカウントを作らず文書作成

 

PLSQLが候補にない。orz

f:id:norihiko_matsumoto:20190422214913p:plain

対応している言語が少ないのかplsqlが出てこない


 

 やむなくSQLにしてハイライト結果を確認するがイマイチだ。

言語によってはきれいに出るのかもしれないが。

hackMD CodiMD

HackMDのPL/SQLのハイライト結果

 さらによくよく考えたらGistで良いんじゃねえか

はてなのヘルプ画面を見ていたら、詳しくはGithubを見ろと書いている。ん!だったらGithubのGistで良いんじゃねえかと思いついた。ただ、URLがバレると文書を覗かれるが、すぐに削除すればいいだろう。。。

gist.github.com

 

ただ、結論からいうとうまくハイライトしてくれなかった。

やっぱりはてなブログのプレビューが最高なのか??

gist

gist でMarkDownでハイライト表示されるかみてみたが。。

 

ぐぐってみるも良いハイライトツールが見つからない。

 

qiita.com

 Googleドキュメントを使うのでただだし、セキュリティも保てそうなので良いかと思ったが、私が仕事でメインで使うVisual Basic.netとPL/SQLに対応していない。

 

 2019年5月17日追記

はてな記法は私が愛用しているAutoHotKeyについても対応している事がわかった。

もうはてな記法一択だね。

 

ソースの解析時に役立つ辞書ツールをAutoHotKeyで作ったので、もしよければそちらも参照してください。

 

www.norick-matsumoto.com