Oracle PL/SQL Language Pocket Reference- P9

Oracle PL/SQL Language Pocket Reference- P9: This pocket guide features quick-reference information to help you use Oracles PL/SQL language. It includes coverage of PL/SQL features in the newest version of Oracle, Oracle8i. It is a companion to Steven Feuerstein and Bill Pribyls bestselling Oracle PL/SQL Programming. Updated for Oracle8, that large volume (nearly 1,000 pages) fills a huge gap in the Oracle market, providing developers with a single, comprehensive guide to building applications with PL/SQL and building them the right way. ...
Nội dung trích xuất từ tài liệu:
Oracle PL/SQL Language Pocket Reference- P9 total_type IN VARCHAR2--ALL or NET ); /* || For every employee hired more than five years ago, || give them a bonus and send them an e-mail notification. */ FOR emp_rec IN emp_cur (ADD_MONTHS (SYSDATE, -60)) LOOP apply_bonus (emp_rec.employee_id); send_notification (emp_rec.employee_id); END LOOP; -- IF :SYSTEM.FORM_STATUS = CHANGED THEN COMMIT; END IF; FUNCTION display_user (user_id IN NUMBER /* Must be valid ID */, user_type IN VARCHAR2) 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. 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. 3.6.1 Comment As You Code 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. 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. 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. 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 fullPlease purchase PDF Split-Merge on www.verypdf.com to remove this watermark. understanding of what the program does or should do. 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. 3.6.2 Explain the Why -- Not the How -- of Your Program What do you think of the comments in the following Oracle Forms trigger code? -- If the total compensation is more than the maximum... IF :employee.total_comp > maximum_salary THEN -- Inform the user of the problem. MESSAGE (Total compensation exceeds maximum. Please re-enter!); -- Reset the counter to zero. :employee.comp_counter := 0; -- Raise the exception to stop trigger processing. RAISE FORM_TRIGGER_FAILURE; END IF; 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. 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? 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? /* Set the number of elements to zero. */ :GLOBAL.num_elements := 0; Once again, the comment adds no value. Does the next comment offer additional information? /* Empty the list of names. */ :GLOBAL.num_elements := 0;Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. 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: PROCEDURE empty_list IS BEGIN :GLOBAL.num_elements := 0; END; Then to empty a list you would not need any comment at all. You could simply include the statement: empty_list; and the meaning would be perfectly clear. 3.6.3 Make Comments Easy to Enter and Maintain You shouldnt 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 shouldnt 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: /* =========================================================== | Parameter Description | | | | company_id The primary key to company | | start_date Start date used for date range ...