Re: Problems retaining what I study

From: stephen booth <stephenbooth.uk_at_gmail.com>
Date: Fri, 19 Aug 2005 16:58:39 +0100
Message-ID: <687bf9c4050819085811e9cc95@mail.gmail.com>

On 19/08/05, Dennis Williams <oracledba.williams_at_gmail.com> wrote:
> I used to work for a software vendor whose policy was "no comments in code".
> Usually I'm a real documentation kind of guy. So I was a bit shocked at this
> policy, to say the least. And this job was writing C code which doesn't have
> a reputation for self-documentation. After working there for awhile, I
> gradually began to see the wisdom of their policy. Consider these points:
> - Comments can be a crutch. If a programmer is forced to rely solely on
> the code, then you tend to make the code more self-documenting. Perhaps
> instead of selecting "A", "B" and so on for variable names, you carefully
> select meaningful names. Or write the code in a straightforward manner
> rather than dazzling with arcane constructions.

My variable names were more like machine_asset_tag or next_maintenence_date. Function names would be things like get_valid_future_date_from_user() or get_string(int string_size).

> - Out-of-date comments can be misleading. People often modify code but
> fail to modify the comments.

True. But I see that as an arguement for making people edit comments on code they've changed rather than just banning people from writing comments.

Also, the comment blocks at the top of functions (and similar) that I mentioned, they would include a change control/record block for maintainers to include the date and description of any changes.

> - Most comments are superfluous, of the variety "the following line sums
> the values of A and B and stores the result in C", followed by C = A + B.
> Having 7 lines of comment per line of code can end up obscuring the code.
>

When I said 7 lines of comment for each line of code I didn't mean:

// comment
// comment
// comment
// comment
// comment
// comment
// comment

code
...

Most (probably around 60-70%) lines of code would have a line of comment associated with them but most of the commenting was in big blocks at the top of each function, procedure or other distinct block of code describing what it did &c.

Stephen

-- 
It's better to ask a silly question than to make a silly assumption.
--
http://www.freelists.org/webpage/oracle-l

Received on Fri Aug 19 2005 - 11:00:45 CDT