oracle pl-sql programming, 2nd edition chapter 3_ effective coding style.htm

SQL 和 data base 学习资料

    <LI class=ListBullet>Scalar variables, such as a VARCHAR2 declaration 
    <P></P>
    <LI class=ListBullet>Complex datatypes, such as records and tables 
    <P></P>
    <LI class=ListBullet>Database-related declarations, such as cursors 
    <P></P>
    <LI class=ListBullet>Named exceptions 
    <P></P>
    <LI class=ListBullet>Modules (procedures and functions) 
    <P></P></LI></UL>
  <P class=Body>As with simple variable declarations, I sometimes have many 
  different but related objects in my package. If so, I might group those types 
  of objects together. But within that grouping, I still follow the above order. 

  <H2 class=HeadA><A name=94685></A>Using Comments Effectively</H2>
  <P class=Body>The object of an effective coding style is to make the program 
  more understandable and maintainable. Most programs will benefit from 
  documentation which explains what is going on inside those programs. There are 
  two forms of code documentation: external and internal. External documentation 
  is descriptive information about a program which is written and stored 
  separately from the program itself. Internal documentation, also known as 
  inline documentation or comments, is placed within the program itself, either 
  at the program level or the statement level. (For an introduction to inline 
  documentation and the types of PL/SQL comments, see the section called 
  "Comments" in Chapter 2.) 
  <P class=Body>The best kind of internal documentation derives from your 
  programming style. If you apply many of the guidelines in this chapter and 
  throughout this book, you will be able to write code which is, to a great 
  extent, self-documenting. Here are some general tips: 
  <UL>
    <LI class=ListBullet>Write straightforward code that avoids clever tricks. 
    <P></P>
    <LI class=ListBullet>Think of names for variables and modules that 
    accurately describe their purpose. 
    <P></P>
    <LI class=ListBullet>Use named constants instead of literal values. 
    <P></P>
    <LI class=ListBullet>Employ a clean, consistent layout. 
    <P></P></LI></UL>
  <P class=Body>Do all these things and more, and you will find that you need to 
  write fewer comments to explain your code. 
  <P class=Body>Reducing the need for comments is important. Few developers make 
  or have the time for extensive documentation in addition to their development 
  efforts, and, more importantly, many comments tend to duplicate the code. This 
  raises a maintenance issue because those comments will have to be changed when 
  the code is changed. 
  <P class=Body>While it is my hope that after reading this book you will write 
  more self-documenting code, there is little doubt that you will still need to 
  comment your code. The following example shows the use of single- and 
  multiline comments in PL/SQL: <PRE><CODE class=CodeIndent>PROCEDURE calc_totals (company_id IN NUMBER,--The company key</CODE>
<CODE class=CodeIndent>                       total_type IN VARCHAR2--ALL or NET</CODE>
<CODE class=CodeIndent>                      );</CODE>
<CODE class=CodeIndent>&nbsp;</CODE>
<CODE class=CodeIndent>/*</CODE>
<CODE class=CodeIndent>|| For every employee hired more than five years ago,</CODE>
<CODE class=CodeIndent>|| give them a bonus and send them an e-mail notification.</CODE>
<CODE class=CodeIndent>*/</CODE>
<CODE class=CodeIndent>FOR emp_rec IN emp_cur (ADD_MONTHS (SYSDATE, -60))</CODE>
<CODE class=CodeIndent>LOOP</CODE>
<CODE class=CodeIndent>   apply_bonus (emp_rec.employee_id);</CODE>
<CODE class=CodeIndent>   send_notification (emp_rec.employee_id);</CODE>
<CODE class=CodeIndent>END LOOP;</CODE>
<CODE class=CodeIndent>&nbsp;</CODE>
<CODE class=CodeIndent>-- IF :SYSTEM.FORM_STATUS = 'CHANGED' THEN COMMIT; END IF;</CODE>
<CODE class=CodeIndent>&nbsp;</CODE>
<CODE class=CodeIndent>FUNCTION display_user </CODE>
<CODE class=CodeIndent>   (user_id IN NUMBER /* Must be valid ID */, user_type IN VARCHAR2)</CODE>
</PRE>
  <P class=Body>The first example uses the single-line comment syntax to include 
  endline descriptions for each parameter in the procedure specification. The 
  second example uses a multiline comment to explain the purpose of the FOR 
  loop. The third example uses the double-hyphen to comment out a whole line of 
  code. The last example embeds a comment in the middle of a line of code using 
  the block comment syntax. 
  <P class=Body>These two types of comments offer the developer flexibility in 
  how to provide inline documentation. The rest of this section offers 
  guidelines for writing effective comments in your PL/SQL programs. 
  <H3 class=HeadB>Comment As You Code</H3>
  <P class=Body>It is very difficult to make time to document your code after 
  you have finished writing your program. Psychologically, you want to (and 
  often need to) move on to the next programming challenge after you get a 
  program working. 
  <P class=Body>You may also have a harder time writing your comments once you 
  have put some distance between your brain cells and those lines of code. Why 
  exactly did you write the loop that way? Where precisely is the value of that 
  global variable set? Unless you have total recall, post-development 
  documentation can be a real challenge. 
  <P class=Body>The last and perhaps most important reason to write your 
  comments as you write your code is that the resulting code will have fewer 
  bugs and (independent of the comments themselves) be easier to understand. 
  <P class=Body>When you write a comment you (theoretically) explain what your 
  code is meant to accomplish. If you find it difficult to come up with that 
  explanation, there is a good chance that you lack a full understanding of what 
  the program does or should do. 
  <P class=Body>The effort that you make to come up with the right comment will 
  certainly improve your comprehension, and may also result in code correction. 
  In this sense, good inline documentation can be as beneficial as a review of 
  your code by a peer. In both cases, the explanation will reveal important 
  information about your program. 
  <H3 class=HeadB>Explain the Why--Not the How--of Your Program</H3>
  <P class=Body>What do you think of the comments in the following Oracle Forms 
  trigger code? <PRE><CODE class=CodeIndent>-- If the total compensation is more than the maximum...</CODE>
<CODE class=CodeIndent>IF :employee.total_comp &gt; maximum_salary</CODE>
<CODE class=CodeIndent>THEN</CODE>
<CODE class=CodeIndent>   -- Inform the user of the problem.</CODE>
<CODE class=CodeIndent>   MESSAGE ('Total compensation exceeds maximum. Please re-enter!');</CODE>
<CODE class=CodeIndent>&nbsp;</CODE>
<CODE class=CodeIndent>   -- Reset the counter to zero.</CODE>
<CODE class=CodeIndent>   :employee.comp_counter := 0;</CODE>
<CODE class=CodeIndent>&nbsp;</CODE>
<CODE class=CodeIndent>   -- Raise the exception to stop trigger processing.</CODE>
<CODE class=CodeIndent>   RAISE FORM_TRIGGER_FAILURE;</CODE>
<CODE class=CodeIndent>END IF;</CODE>
</PRE>
  <P class=Body>None of these comments add anything to the comprehension of the 
  code. Each comment simply restates the line of code, which in most cases is 
  self-explanatory. 
  <P class=Body>Avoid adding comments simply so that you can say, "Yes, I 
  documented my code!" Rely as much as possible on the structure and layout of 
  the code itself to express the meaning of the program. Reserve your comments 
  to explain the Why of your code: What business rule is it meant to implement? 
  Why did you need to implement a certain requirement in a certain way? 
  <P class=Body>In addition, use comments to translate internal, 
  computer-language terminology into something meaningful for the application. 
  Suppose you are using Oracle Forms GLOBAL variables to keep track of a list of 
  names entered. Does the following comment explain the purpose of the code or 
  simply restate what the code is doing? <PRE><CODE class=CodeIndent>/* Set the number of elements to zero. */</CODE>
<CODE class=CodeIndent>:GLOBAL.num_elements := 0;</CODE>
</PRE>
  <P class=Body>Once again, the comment adds no value. Does the next comment 
  offer additional information? <PRE><CODE class=CodeIndent>/* Empty the list of names. */</CODE>
<CODE class=CodeIndent>:GLOBAL.num_elements := 0;</CODE>
</PRE>
  <P class=Body>This comment actually explains the purpose of the assignment of 
  the global to zero. By setting the number of elements to zero, I will have 
  effectively emptied the list. This comment has translated the "computer lingo" 
  into a description of the effect of the statement. Of course, you would be 
  even better off hiding the fact that you use this particular global variable 
  to empty a list and instead build a procedure as follows: 
  <P class=CodeIndentKeep>PROCEDURE empty_list IS 
  <P class=CodeIndentKeep>BEGIN 
  <P class=CodeIndentKeep>:GLOBAL.num_elements := 0; <PRE><CODE class=CodeIndent>END;</CODE>
</PRE>
  <P class=Body>Then to empty a list you would not need any comment at all. You 
  could simply include the statement: <PRE><CODE class=CodeIndent>empty_list;</CODE>
</PRE>
  <P class=Body>and the meaning would be perfectly clear. 
  <H3 class=HeadB>Make Comments Easy to Enter and Maintain</H3>
  <P class=Body>You shouldn't spend a lot of time formatting your comments. You 
  need to develop a style that is clean and easy to read, but also easy to 
  maintain. When you have to change a comment, you shouldn't have to reformat 
  every line in the comment. Lots of fancy formatting is a good indication that 
  you have a high-maintenance documentation style. The following block comment 
  is a maintenance nightmare: <PRE><CODE class=CodeIndent>/*</CODE>
<CODE class=CodeIndent>===========================================================</CODE>
<CODE class=CodeIndent>| Parameter          Description                          |</CODE>
<CODE class=CodeIndent>|                                                         |</CODE>
<CODE class=CodeIndent>| company_id         The primary key to company           |</CODE>
<CODE class=CodeIndent>| start_date         Start date used for date range       |</CODE>
<CODE class=CodeIndent>| end_date           End date for date range              |</CODE>
<CODE class=CodeIndent>===========================================================</CODE>
<CODE class=CodeIndent>*/</CODE>
</PRE>
  <P class=Body>The right-justified vertical lines and column formatting for the 
  parameters require way too much effort to enter and maintain. What happens if 
  you add a parameter with a very long name? What if you need to write a longer 
  description? A simpler and more maintainable version of this comment might be: 
<PRE><CODE class=CodeIndent>/*</CODE>
<CODE class=CodeIndent>===========================================================</CODE>
<CODE class=CodeIndent>| Parameter - Description               </CODE>
<CODE class=CodeIndent>|                                                         </CODE>
<CODE class=CodeIndent>| company_id - The primary key to company </CODE>
<CODE class=CodeIndent>| start_date - Start date used for date range </CODE>
<CODE class=CodeIndent>| end_date - End date for date range       </CODE>
<CODE class=CodeIndent>===========================================================</CODE>
<CODE class=CodeIndent>*/</CODE>
</PRE>
  <P class=BodyKeep>I like to use the following format for my block comments: <PRE><CODE class=CodeIndent>/*</CODE>
<CODE class=CodeIndent>|| I put the slash-asterisk that starts the comment on a line all by</CODE>
<CODE class=CodeIndent>|| itself. Then I start each line in the comment block with a double</CODE>
</PRE>
  <P class=CodeIndentKeep>|| vertical bar to highlight the presence of the 
  comment. Finally, 
  <P class=CodeIndentKeep>|| I place the asterisk-slash on a line all by itself. 
<PRE><CODE class=CodeIndent>*/</CODE>
</PRE>
  <P class=Body>On the negative side, the vertical bars have to be erased 
  whenever I reformat the lines, but that isn't too much of an effort. On the 
  positive side, those vertical bars make it very easy for a programmer who is 
  scanning the left side of the code to pick out the comments. 
  <P class=Body>I put the comment markers on their own lines to increase the 
  whitespace in my program and set off the comment. That way I can avoid "heavy" 
  horizontal lines full of delimiters, such as asterisks or dashes, and avoid 
  having to match the longest line in the comment. 
  <H3 class=HeadB>Maintain Indentation</H3>
  <P class=Body>Inline commentary should reinforce the indentation and therefore 
  the logical structure of the program. For example, it is very easy to find the 
  comments in the make_array procedures shown below. I do not use any 
  double-hyphens, so the slash-asterisk sequences stand out nicely. In addition, 
  all comments start in the first column, so I can easily scan down the 
  left-hand side of the program and pick out the documentation: <PRE><CODE class=CodeIndent>PROCEDURE make_array (num_rows_in IN INTEGER) </CODE>
<CODE class=CodeIndent>/* Create an array of specified numbers of rows */</CODE>
<CODE class=CodeIndent>IS</CODE>
<CODE class=CodeIndent>/* Handles to Oracle Forms structures */</CODE>
<CODE class=CodeIndent>   col_id GROUPCOLUMN;</CODE>
<CODE class=CodeIndent>   rg_id RECORDGROUP;</CODE>
<CODE class=CodeIndent>BEGIN</CODE>
<CODE class=CodeIndent>/* Create new record group and column */</CODE>
<CODE class=CodeIndent>   rg_id := CREATE_GROUP ('array');</CODE>
<CODE class=CodeIndent>   col_id := ADD_GROUP_COLUMN ('col');</CODE>
<CODE class=CodeIndent>/* </CODE>
<CODE class=CodeIndent>|| Use a loop to create the specified number of rows and </CODE>
<CODE class=CodeIndent>|| set the value in each cell.</CODE>
<CODE class=CodeIndent>*/</CODE>
<C