|
|
|
|
| Re: How to document any oracle package.? [message #247026 is a reply to message #247006] |
Fri, 22 June 2007 21:57   |
rleishman
Messages: 3728
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 |
Frank
Messages: 7901
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 |
rleishman
Messages: 3728
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 |
Frank
Messages: 7901
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 |
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
|
|
|
|
|
|
] 
Blog
Search
Help
Members
Register
Login
Home
