RE: [sqr-users] SQR Standards

["Alexander, Steve" <Steven.Alexander@sanjoseca.gov>]

Robert has an excellent point about cleaning up code that has been commented
out.  The only difference between an active statement and a commented-out
statement is that thin exclamation mark in the first column of the line.  It
slows down and confuses the programmer who now has two opposite or worse
slightly different commands in his or her memory:


! if #x > 0
if #x < 0


Ok, now look away from the page, wait a minute, and try to remember - are we
performing a block of code for negative numbers or for positive numbers?
Now multiply that by thirty spots throughout the program.  

-----Original Message-----
From: Robert Goshko [mailto:robert.goshko@gmail.com] 
Sent: Monday, November 21, 2005 11:01 AM
To: This list is for discussion about the SQR database reporting
languagefrom Hyperion Solutions.
Subject: Re: [sqr-users] SQR Standards

On 21/11/05, Bob Stone <bstone@fastenal.com> wrote:
> I agree with everything Steve mentioned.

I second that as well

> The only thing I would add is that I find it visually useful to have
comments at the beginning of each procedure explaining what it does, and
that for each procedure in that SQR the comments are formatted the same.
This allows someone to scroll down the program, and notice a) where one
procedure ends and another starts, b) what a procedure does without digging
into the logic for it.  It allows a 2nd programmer to come in and see what a
program does (underlying logic) without getting lost in the nitty-gritty of
the code, or missing a procedure somewhere in the middle.
>
>
>
> !-----------------------------------------------------------------------!
> ! Procedure:    Set-Route-to-PS-Vars                                    !
> ! Desc:         Procedure to set up variables needed in for the insert  !
> !               to the DEP/DEP3 tables.                                 !
> !-----------------------------------------------------------------------!
> begin-procedure Set-Route-to-PS-Vars
>
> ...
>
> end-procedure Set-Route-to-PS-Vars

I would try to keep this comment a little general because if it too
specific, after X number of revisions something may have gotten moved
and the comment not updated.

There are those that will tell you never to delete code, just comment
it out, I prefer to let a revision control system keep track of this
(RCS, PVCS, SourceSafe, etc), doesn't matter which one, just use one. 
After a couple of years of maintenance, the source code starts to get
messy with thing being commented out and code added in.

--
...Rob

-- No trees were killed in the sending of this message.  However a
large number of electrons were terribly inconvenienced.

================================================
Robert Goshko
Registered Linux User #260513

Want a Gmail account, 2.6+ GB web mail (for free),  just ask me.

_______________________________________________
sqr-users mailing list
sqr-users@sqrug.org
http://www.sqrug.org/mailman/listinfo/sqr-users

_______________________________________________
sqr-users mailing list
sqr-users@sqrug.org
http://www.sqrug.org/mailman/listinfo/sqr-users