DBFlute-1.1だとこうなるシリーズ、
ごめんなさい、まだあるんです。
わりと些細なことですが、ちょっと思い切りました。
外だしSQLのコメントのことです。
そもそも外だしSQLのコメントって？
こんなやつです。
select ...
from ...
where ...
order by ...
という感じで、SQLのタイトルと説明を書くコメントです。
[df:title] と [df:description] と入れることで、
JavaDocコメントや SchemaHTML に反映されます。
例えば、こんなかんじです。
-> SchemaHTML - OutsideSql List
1.0.xではもちろんゆるい
1.0.xでは、デフォルトでは何もチェックされません。
外だしSQLのコメントをチェックするオプションがあります。
outsideSqlDefinitionMap.dfpropにて、
; isRequiredSqlTitle = true
; isRequiredSqlDescription = true
とすると、OutsideSqlTestタスクにて、
(outside-sql-test.batを叩くと)
もし、コメントがないSQLがあったらタスクが落ちます。
別に、Sql2Entityではチェックがかからないので、
ちょっと弱いチェックではあります。
SQLこそコメントを
もう、詳しく説明するまでもないですね。
ですが、やっぱり現場のSQL、
無言でわけわからないものが多いものなのです。
Javaのプログラムは、
まだ Eclipse など支援でソースを追っかけやすかったり、
そもそもコメントを書く習慣が付いてる人が多かったりと、
まだ良い方だとは思います。
SQLは、とっても自由な言語であるため、
「絶妙なロジック」
なることが多いため、
何も書いてないと何をやっているのかをわからない。
最初に書いた人じゃない人が修正しようにも、
手の出しようがないという状況が起きやすいのです。
あまり変更をしないシステムであればまだいいのですが、
特に DBFlute は変化の激しい現場を想定したツールです。
DBFluteの外だしSQLでは、ぜひともコメントを
「ちょっとでも」
いいので書いて欲しいという気持ちがあります。
それが、
そのSQLで一言で言うと何？
と、
そのSQLをメンテする人に残しておきたい言葉は？
です。
それを、
[df:title] と [df:description] で残しておいて欲しいなと。
JavaDoc や SchemaHTML にも表示されるとあれば、
コメントを書くモチベーションもちょっとは上がるかなって。
ということでSql2Entityでも
ということで、
チェックをデフォルト設定で必須にしようかなと。
DBFluteであれば、そもそも外だしSQLは極端に少なくなります。
それでも外にだされたSQLは、
「コメントが必要なほどの複雑で役割重要なSQL」のはずです。
で、それならば、本当は Sql2Entity でもチェックすべきでしょ、
ということで、Sql2Entity でもチェックするようにしました。
これは強力です。コメント書かないと先に進まないということなので。
迷ったのは、
「エラーでよくわからないので、いいや自分でクラス作っちゃえ」
ってなるとやだなぁと思ったのですが、ここは、
SQLのため
にも...ね。
その分、例外メッセージはしっかりしたものにします。
もちろん、外せます
コメントを書くメドが立たないなら、
outsideSqlDefinitionMap.dfprop にて、
; isRequiredSqlTitle = false
; isRequiredSqlDescription = false
とすると、何もしません。
また、
; isCheckRequiredSqlCommentAlsoSql2Entity = false
とすると、Sql2Entityではチェックしなくなります。
OutsideSqlTest だけでチェックしたい場合はこちら。
