This discussion is archived
1 2 Previous Next 15 Replies Latest reply: Apr 2, 2013 4:59 AM by 947771 RSS

pls tel me appropriate place to put description about sp in sp.

947771 Newbie
Currently Being Moderated
hi,

This is how SP is created, please tel me which is the appropriate place to put description about SP in sp?

CREATE OR REPLACE PROCEDURE PROCEDURE
(
PARAM1 IN VARCHAR2
, PARAM2 IN VARCHAR2
) AS
BEGIN
NULL;
END PROCEDURE;

yours sincerely

Edited by: 944768 on Mar 27, 2013 10:28 PM
  • 1. Re: pls tel me appropriate place to put description about sp in sp.
    jeneesh Guru
    Currently Being Moderated
    944768 wrote:
    hi,

    This is how SP is created, please tel me which is the appropriate place to put description about SP in sp?
    CREATE OR REPLACE PROCEDURE PROCEDURE
    --Versioning Info, if required. This will capture the author, changes...
    --Description
     (
       PARAM1 IN VARCHAR2  
     , PARAM2 IN VARCHAR2  
     ) AS 
     BEGIN
       NULL;
     END PROCEDURE;
  • 2. Re: pls tel me appropriate place to put description about sp in sp.
    S10390 Journeyer
    Currently Being Moderated
    If you are creating the SP by using a GUI tool ( like PLSQL Developer / Toad ) , the description, user created, version info will be automatically added.

    If you want you can also change it.

    Sample below

    create or replace procedure proc_name (param1 varchar2, param2 varchar2)
    is

    --==================================================================================
    -- application : Appliication_name
    -- description : Sample Description
    --
    -- usage : <Sample Usage>
    -- modification history:-
    -- ====================================
    -- date name comments
    --====================================
    -- <date> <created by>     initial creation.
    --==================================================================================
    begin
  • 3. Re: pls tel me appropriate place to put description about sp in sp.
    Frank Kulash Guru
    Currently Being Moderated
    Hi,
    944768 wrote:
    hi,

    This is how SP is created, please tel me which is the appropriate place to put description about SP in sp?
    Do not put comments here, before the CREATE PROCEDURE statement. They will not be stored in the data dictionary.
    CREATE OR REPLACE PROCEDURE PROCEDURE
    (
    PARAM1 IN VARCHAR2
    , PARAM2 IN VARCHAR2
    ) AS
    If I have a comment that expalins what the procedure does overall, and/or shows how to call it, then I'll usually put it here in a stand-alone procedure.
    BEGIN
    NULL;
    END PROCEDURE;
    However, I rarely write stand-alone procedures. Almost all of the procedures and functions I write are in packages. In packages, I put big, general comments before the PROCEDURE (or FUNCTION) statement.

    More specific comments; e.g. what a particular variable is for, or what is happending in an IF...THEN...ELSE block, go on the same line, or right next to, the code on which they comment.

    Where you put comments is a lot less important than whether you write comments.
  • 4. Re: pls tel me appropriate place to put description about sp in sp.
    BillyVerreynne Oracle ACE
    Currently Being Moderated
    S10390 wrote:
    If you are creating the SP by using a GUI tool ( like PLSQL Developer / Toad ) , the description, user created, version info will be automatically added.

    If you want you can also change it.

    Sample below

    create or replace procedure proc_name (param1 varchar2, param2 varchar2)
    is

    --==================================================================================
    -- application : Appliication_name
    -- description : Sample Description
    --
    -- usage : <Sample Usage>
    -- modification history:
    -- ====================================
    -- date name comments
    --====================================
    -- <date> <created by>     initial creation.
    --==================================================================================
    begin
    Too much fluff. This is 80's style of commenting code. 40 years old and totally out of date in today's SDLCs and development environments, using today's s/w development tools.

    Comments need to be brief, specific, and address the WHY and not the WHAT.
  • 5. Re: pls tel me appropriate place to put description about sp in sp.
    BillyVerreynne Oracle ACE
    Currently Being Moderated
    944768 wrote:

    This is how SP is created, please tel me which is the appropriate place to put description about SP in sp?
    I agree with Frank.

    The important point is to provide MEANINGFUL comment that the developer reading, using, debugging and maintaining that code, need to UNDERSTAND the code.

    And it does not just limited to comments. It also needs PROPER coding standards and naming conventions. Which means NOT abusing uppercase as your code does. Using the programming standards of today that are used for Java, .Net, Ada (PL/SQL's parent language), Pascal, Visual Basic, C/C++ etc.

    All these languages share a common set of standards that have matured over many years now. Learn when to use lowercase, pascalcase, camelcase and uppercase. Writing source code in all uppercase is a stupid thing to do. Writing reserved words in uppercase is also a stupid thing to do. Especially as Ada standards (PL/SQL is an implementation of Ada) does not have any such standards.

    Lastly, when commenting you need to tell the person WHY you did that. Not WHAT.

    The WHAT is done is stated by the program statements coded. E.g.
    UTL_FILE.fOpen( .. );
    We all know that a file is being opened. So the following comment is meaningless:
    --// open CSV exception file
    UTL_FILE.fOpen( .. );
    The question is, for example. why is a file being opened in the code? So commenting on that provides additional understanding to the person using/reading that code:
    --// when new business rules are violated during invoice processing,
    --// these violations need to be written in CSV format to file where
    --// business users can download it from the local web server
    UTL_FILE.fOpen( .. );
    Not the best of examples, but you'll get the idea I hope.
  • 6. Re: pls tel me appropriate place to put description about sp in sp.
    997945 Newbie
    Currently Being Moderated
    We rarely create individual SP. Its mostly inside packages. The comments about what the Procedure does can be just put above the Procedure definition.

    /******************************************************************************************
    * Function : XXXX
    * Purpose : This Function does XXXX
    *
    * Return Parameter : Return Status 1 for Success and 0 for Failure
    * Input Parameters : Describe Input Parameter
    * Output Parameters : Describe Output Parameter
    *
    * Author Date Ver Description
    * ------- ------ ---- ---------------
    * XXXX XXXX XXXX XXXXXXXXX
    ******************************************************************************************/
  • 7. Re: pls tel me appropriate place to put description about sp in sp.
    947771 Newbie
    Currently Being Moderated
    can i have a specimen. (a structure)

    yours sincerely
  • 8. Re: pls tel me appropriate place to put description about sp in sp.
    BluShadow Guru Moderator
    Currently Being Moderated
    I think perhaps you need a pair of glasses. Which one of the previous responses does not answer the question?
  • 9. Re: pls tel me appropriate place to put description about sp in sp.
    rp0428 Guru
    Currently Being Moderated
    >
    Too much fluff. This is 80's style of commenting code. 40 years old and totally out of date in today's SDLCs and development environments, using today's s/w development tools.
    >
    Totally disagree. That isn't too much 'fluff' at all.

    All code should have a comment header such as that provided to provide a place for a brief description and, more importantlyk, the change history of the code.

    In many business this change history will include: who made the change, the date of the change, the bug tracking number of the bugs that the change addresses.

    All of that is important to capture IN the procedure header itself so that anyone looking at the code can tell immediately what version of the code they are looking at.
    >
    Comments need to be brief, specific, and address the WHY and not the WHAT.
    >
    If you are talking about comments within the code itself (rather than the header discussed above) then I disagree again.

    The WHAT is often the most important part. Any complex query should have at least a one-line comment stating WHAT the query is doing. It often isn't at all obvious WHAT a query is really trying to do when there are multiple nested statements and complex query predicates.

    A simple 'query all records that are INACTIVE and are for the eastern region' is a WHAT and is much more useful than just looking at a query predicate:
    WHERE ('stat_code in (2, 5, 8) and state_code in ('FL', 'NJ'));
    Complex predicates literally cry out for a WHAT to explain, in English, WHAT DATA the query is supposed be dealing with.

    The code is all about WHAT it is doing and seldom about the WHY you are doing it. The only WHY that is needed is WHY the code does things a particular way. For example to explain why an EXISTS clause is specifically used ('AND DON'T CHANGE IT!) instead of an IN clause. Or why a particular query construct is being used.

    Both WHAT and WHY are appropriate as long as they are not overused. In my experience I seldom see overuse of comments.
  • 10. Re: pls tel me appropriate place to put description about sp in sp.
    rp0428 Guru
    Currently Being Moderated
    >
    The important point is to provide MEANINGFUL comment that the developer reading, using, debugging and maintaining that code, need to UNDERSTAND the code.
    . . .
    Lastly, when commenting you need to tell the person WHY you did that. Not WHAT.
    >
    And for that it is the WHAT that is often the most important part. To understand the code you first have to know WHAT it is supposed to be doing.

    From the code perspective of understanding a particular piece of code it doesn't matter much WHY the code exists. The first reality is that it does exist but WHAT is is trying to do.
    >
    The WHAT is done is stated by the program statements coded. E.g.
    UTL_FILE.fOpen( .. );
    Only at the language level. That says NOTHING about WHAT is being done at the business level. There is plenty of documentation that a developer can look up to find out what the language itself is doing.

    The problem when evaluating code is finding out the business purpose of the code.
    >
    We all know that a file is being opened. So the following comment is meaningless:

    --// open CSV exception file
    UTL_FILE.fOpen( .. );
    >
    But the comment is providing information about the BUSINESS PURPOSE and type of file. It is an exception file in CSV format. The CSV information can be an important clue if the code isn't working properly.

    I agree that for some simple one-liners like that example a short description in the code 'header' comment area can cover that by saying the code reads a CSV exception file and ...
    >
    The question is, for example. why is a file being opened in the code? So commenting on that provides additional understanding to the person using/reading that code:

    --// when new business rules are violated during invoice processing,
    --// these violations need to be written in CSV format to file where
    --// business users can download it from the local web server
    UTL_FILE.fOpen( .. );
    >
    Now much of THAT is fluff. It is pretty irrelevant whether or not 'business users can download it from the local web server'.

    A simple one-liner says all that is needed.
    >
    write business rule violations to a CSV file.
    >
    The 'business user' part is irrevelant, serves no useful purpose in understanding or maintaining the code and so has no place in the code. That part of the statement belongs in the Functional or Technical Requirements Documents.
  • 11. Re: pls tel me appropriate place to put description about sp in sp.
    S10390 Journeyer
    Currently Being Moderated
    If a stand alone procedure was created using even Toad 11, all these description info will appear to edit. We can add the comments in the procedure, as said WHAT and WHY format wherever required. But to get a brief idea on the procedure, hope we need to have such description and this is not 80's style of commenting code i belive.
  • 12. Re: pls tel me appropriate place to put description about sp in sp.
    BillyVerreynne Oracle ACE
    Currently Being Moderated
    S10390 wrote:
    If a stand alone procedure was created using even Toad 11, all these description info will appear to edit. We can add the comments in the procedure, as said WHAT and WHY format wherever required. But to get a brief idea on the procedure, hope we need to have such description and this is not 80's style of commenting code i belive.
    With 80's style I was referring to massive comment header blocks that had to be added to each program unit and maintained.

    One example. A version number in a comment header block for a stored procedure or a function, is mere text and useless. Cannot be used for conditional installation. Cannot be used for conditional compilation. So just what is the purpose of adding version numbers in a comment block? What is gained by it?

    The point is not to saddle code with useless "red tape/standards". In many years of programming, I have seen large comment header blocks been copy and pasted, and NOT maintained. Which means a year or so later, after a couple of updates, this large comment block with all the details, does not reflect what that code currently does.

    Do some research on how to effectively comment code. There are some basic principles:
    - well design modules will do one primary task, will have a name describing that task, and do not need an essay to make someone else understand the module
    - unless absolutely necessary, do not include any code in your comments
    - do not explain what a program statement does, explain why it is used
    etc.
  • 13. Re: pls tel me appropriate place to put description about sp in sp.
    BillyVerreynne Oracle ACE
    Currently Being Moderated
    You are (again) misconstruing what I stated.
  • 14. Re: pls tel me appropriate place to put description about sp in sp.
    S10390 Journeyer
    Currently Being Moderated
    There are some basic principles:
    - well design modules will do one primary task, will have a name describing that task, and do not need an essay to make someone else understand the module
    - unless absolutely necessary, do not include any code in your comments
    - do not explain what a program statement does, explain why it is used

    Agree with these...Thanks Billy.
1 2 Previous Next

Legend

  • Correct Answers - 10 points
  • Helpful Answers - 5 points