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，大家可以自己試一下，看看概要內容是什么情況。