PLSQL的注释技巧

概述

这里提供一些注释的技巧，用来模仿Java中的文档注释的功能。
在Eclipse中，鼠标悬浮在类或其成员上，会显示相关的文档注释；在PL/SQL中也有类似的功能，我们需要掌握一些注释技巧，让其可读性更高。

正文

1. 不要在最上面写注释

第一个有效指令前的内容，都是被直接无视的；不会格式化，也不会存储。假如你像下面这样写注释：

/*
名字解析：案事件-文书相关-为换押证生成文书字号。
这个过程是对ASJ_GENHYZWORD的一次重构。
*/
create or replace procedure asj_ws_generateWordMarkForHYZ(in_writid      in varchar2, -- 文书实例编号
in_increment   in integer, -- 增量，在一书多人时需要同时为多个文书生成序列号
out_wordofwrit out varchar2, -- 文书字
out_markofwrit out integer -- 文书号
) is

编译，关掉当前窗口，重新打开这个过程，你会发现是这样子的：

2. 如何强制格式化在某处换行

也许你想这样写头部：

create or replace procedure asj_ws_generateWordMarkForHYZ
(in_writid      in varchar2, -- 文书实例编号
in_increment   in integer, -- 增量，在一书多人时需要同时为多个文书生成序列号
out_wordofwrit out varchar2, -- 文书字
out_markofwrit out integer -- 文书号
) is

但是PL/SQL格式化之后，又会变成这样子：

create or replace procedure asj_ws_generateWordMarkForHYZ(in_writid      in varchar2, -- 文书实例编号
in_increment   in integer, -- 增量，在一书多人时需要同时为多个文书生成序列号
out_wordofwrit out varchar2, -- 文书字
out_markofwrit out integer -- 文书号
) is

此时，我们可以使用注释来强制换行：

create or replace procedure asj_ws_generateWordMarkForHYZ --
(in_writid      in varchar2, -- 文书实例编号
in_increment   in integer, -- 增量，在一书多人时需要同时为多个文书生成序列号
out_wordofwrit out varchar2, -- 文书字
out_markofwrit out integer -- 文书号
) is

这样，即使格式化，也不会违背我们的换行意愿了。另外，多行注释也可以实现。

再比如，你想实现这样的格式：

select ajbh, ajmc
into ajbh, ajmc
from b_asj_aj
where rownum = 1;

但是PL/SQL的格式化会认为没有必要，而将其缩减到一行：

select ajbh, ajmc into ajbh, ajmc from b_asj_aj where rownum = 1;

你可以这样写：

select ajbh, ajmc --
into ajbh, ajmc --
from b_asj_aj --
where rownum = 1;

3. 概要内容在is关键词之前

这里我们把鼠标悬浮在某个过程名而出现的浮动框中的内容称为概要，比如：



这里可以看到，概要只包含is之前的内容；另外，这个框太长了，浪费了空间，这时候上面讲的强制换行就可以起作用了。我们可以这样写：

create or replace procedure asj_ws_generateWordMarkForHYZ
/*
名字解析：案事件-文书相关-为换押证生成文书字号。
这个过程是对ASJ_GENHYZWORD的一次重构。
*/
(in_writid      in varchar2, -- 文书实例编号
in_increment   in integer, -- 增量，在一书多人时需要同时为多个文书生成序列号
out_wordofwrit out varchar2, -- 文书字
out_markofwrit out integer -- 文书号
) is

这样写的好处有几点：1. 我们在合适的位置加入了对于这个过程的说明，而且在概要中将显示这些内容；2. 我们对于换行的控制，会控制概要悬浮框的长度。

再看现在的概要框：



注意：在这里，as并不能取代is，大家可以自己试一下，看看概要内容是什么情况。