Home » Other » General » How to document any oracle package.?
How to document any oracle package.? [message #246925] Fri, 22 June 2007 08:32 Go to next message
misragopal
Messages: 125
Registered: June 2005
Location: New Delhi, india
Senior Member

hi,
How to document an user defined oracle package? this package contains 17 procedures and 8 function. what will be the best suitable methodology to document it.
Re: How to document any oracle package.? [message #247006 is a reply to message #246925] Fri, 22 June 2007 15:41 Go to previous messageGo to next message
Littlefoot
Messages: 20900
Registered: June 2005
Location: Croatia, Europe
Senior Member
Account Moderator
Put several sentences into the package (as a comment) - those lines will help anyone who revisits your code. Complete documentation should be done the way you use as a standard in your company (or wherever you are, even at home). Is it a MS Word document, plain text file, specialized software ... doesn't matter.
Re: How to document any oracle package.? [message #247026 is a reply to message #247006] Fri, 22 June 2007 21:57 Go to previous messageGo to next message
rleishman
Messages: 3724
Registered: October 2005
Location: Melbourne, Australia
Senior Member
In the package spec, describe what of the externally available procedures and functions do: What are their inputs and outputs, what can the caller expect to happen when they call them, and what errors might be returned that need to be handled.

Doco in the package body is for future programmers. Describe complex algorithms, reasons for doing something a certain way - anything that helps a newcomer read the code.

Ross Leishman
Re: How to document any oracle package.? [message #247059 is a reply to message #247026] Sat, 23 June 2007 06:22 Go to previous messageGo to next message
Frank
Messages: 7880
Registered: March 2000
Senior Member
Word of warning here:
Ross' advice is good, as long as you intend to keep the comments up-to-date. If your project/company/whatever has a history of sloppy documenting, it might be a better idea to use less detailed comments.
Better no comments than wrong comments about the purpose of functions/procedures and their parameters.

[Edit: typo]

[Updated on: Sat, 23 June 2007 06:23]

Report message to a moderator

Re: How to document any oracle package.? [message #247100 is a reply to message #247059] Sun, 24 June 2007 01:58 Go to previous messageGo to next message
rleishman
Messages: 3724
Registered: October 2005
Location: Melbourne, Australia
Senior Member
Frank wrote on Sat, 23 June 2007 21:22
Word of warning here:
Ross' advice is good, as long as you intend to keep the comments up-to-date. If your project/company/whatever has a history of sloppy documenting, it might be a better idea to use less detailed comments.
Better no comments than wrong comments about the purpose of functions/procedures and their parameters.



Hmmm. Is there a bit of "Can't win don't try." going on here?

I completely accept that it's a judgement call - and we can probably just agree to disagree - but I think the lowest-common-denominator approach will only make the situation worse. Graddies and juniors will look to the senior developers to set an example. If they see great code well documented then they will try to copy it.

Like I said, it's just an opinion.

Ross Leishman
Re: How to document any oracle package.? [message #247111 is a reply to message #247100] Sun, 24 June 2007 03:14 Go to previous messageGo to next message
Frank
Messages: 7880
Registered: March 2000
Senior Member
Ok. Guess I should have put that in other words.
If you are going to use detailed comments in your code, which is a very good idea, you should reserve time for code-reviews. In these reviews the comments should be checked for validity as well.
Make sure you convince each and every member of your project team of the importance of 100% accurate comments.
If you are not willing to spend project-time on that, you'd be better of with less detailed comments, which, in the end will lead to more time spent before existing code can be either reused or debugged.
Re: How to document any oracle package.? [message #247369 is a reply to message #247111] Mon, 25 June 2007 12:39 Go to previous messageGo to next message
andrew again
Messages: 2577
Registered: March 2000
Senior Member
Partially off topic - but consider documenting views too.
create or replace view v1 as
(
/*
|| this is my view
*/
select * from dual)
/


Sometimes useful to comment tables and/or collumns too...

-- Extract existing comments to script
-- edit script
-- re-run against database to update comments


set linesize 200
set trimspool on
set pagesize 0
set echo off
spool t.sql

 select 'comment on table '||table_name|| 
        ' is '''||replace(comments, '''', '''''')||''';' 
 from user_tab_comments;
 


 select 'comment on column '||table_name||
        '.'||column_name ||' is '''||replace(comments, '''', '''''')||''';' 
 from user_col_comments;

spool off
Re: How to document any oracle package.? [message #249557 is a reply to message #247369] Thu, 05 July 2007 00:52 Go to previous message
misragopal
Messages: 125
Registered: June 2005
Location: New Delhi, india
Senior Member

Thanks friends, i really learn a lot.
Previous Topic: How Oracle 10g searching Queries?
Next Topic: SGA Component
Goto Forum:
  


Current Time: Wed Dec 07 22:38:22 CST 2016

Total time taken to generate the page: 0.11124 seconds