Comments
Scout
comments.
Like a lot of others who contributed to that thread, I will often spend
time "reducing" the number of lines of code in a program, module or
whatever.
Generally this reduction means that the processor has fewer instructions
to execute in order to achieve a specific task.
Sometimes it means quite the opposite, but that readability of the
source has been enhanced. Unless there is a big difference between
execution speed and readability, I'll plump for the readbility every
time.
Code generators are great, but are not good at creating meaningful
comments.
I've just looked through some of the VCL source, and have noticed that
while there are comments used to indicate the beginning or end of a
section of code, there are relatively few comments about what the code
DOES unless what it is doing is non-obvious. And then those comments
are generally well-written and helpful.
Some of the asm routines are not obvious, but are not commented with a
pascal-like equivalent or any description of what is going on. I guess
that these routines are only for the not-faint-of-heart to try to
understand, and if you qualify, you can read them anyway.
Looking through my own code, I find that whilst my commenting is a bit
erratic, at least the truly weird stuff is explained somewhere.
And peering at some of my colleague's source files, I find that some use
comments as a "Note to self - fix this later", some use comments well,
some use comments only as a "this bit didn't work, so I've re-written it
below, but I'm too scared to delete the original implementation so I've
commented it out", and still others don't use comments at all!
I prefer to use the approach (and try to make sure I actually do) where
I assume that the reader of the source (possibly me, years later) has a
reasonably good grasp of the Delphi language, and only needs help (and
extra comments) when
- the code uses some obscure language construct
- the code relies on a "friend" or similar device to operate
- the context (such as thread context) is important
- it is an ugly hack that is needed for some sort of historical reason
- it depends on a certain version of some other software (e.g. db)
- there is some kind of business rule which the implementation doesn't
adequately explain
What rules do you use in deciding what (and what not) to comment?
Scout
Kristofer Skaug
>
> What rules do you use in deciding what (and what not) to comment?
I like your heuristics as a starting point ("must-have" commenting
situations).
Myself I tend to comment rather more than less, when in doubt. I have too
many times noticed that "simple, obvious" things (to me) are far from
obvious to a colleague who has to jump in and fix something in my code.
Of course I don't mean stupid things like "inc(i); // increase i by one"
type comments; but rather the goings-on at application levels higher than
that - there's plenty of medium-to-high-level stuff that warrants an
explanation.
For example, the allocation cycle for a global (or class-field) pointer:
Where is it allocated, where is it freed? How is the "soundness" of its
life cycle guaranteed? How is this memory buffer access protected
(multithreaded access)? etc.
So as time allows, I try to explain what my code does (the design behind
it) in unit headers; example usage; etc (if it's a reusable class). Also,
I am fairly pedantic about commenting each procedure/function with a
header that describes its interface (contract) as accurately as possible.
After all, the contract is often not really obvious from the code; and if
even you think it is, it could still be the "wrong" implementation
(incorrect w.r.t. its specification). What are the assumed and validated
preconditions? postconditions? error cases? side effects? etc.
It should be clear that simple GUI code (e.g. menu- or button-click
handlers) will never be exhaustively documented in this respect ("dear
code reviewer, let me explain to you how we don't give a bleep what
"Sender" is, in procedure TForm1.StartButtonClick(Sender:TObject), and
why you should be glad that we don't waste your time...").
At the final "end;" statement of each procedure I generally insist on
using a 'trailer' comment reflecting the procedure name on so as to
improve visibility when you approach a function "from below" (scrolling
up in the editor). This being done, it is less important to try to
"conserve vertical real-estate" for the purpose of viewing as much code
as possible in a single screenful.
In fact, I have over the years increasingly moved away from this
objective (e.g. being more generous with line breaking and full-block
comments, whitespace to clearly separate distinct code blocks etc) and
now try to promote readability and testability of the code (e.g. some
code coverage tools having issues with multiple statements on a single
line).
--
Kristofer
K. Sallee
> Code generators are great, but are not good at creating meaningful
> comments.
a classic on the topic:
http://mindprod.com/unmaindocumentation.html
Kevin
--
Using M2, Opera's revolutionary e-mail client: http://www.opera.com/m2/
Kristofer Skaug
>
> http://mindprod.com/unmaindocumentation.html
:-),
but I feel that #1 ("Lie in the comments: <..> just fail to keep comments
as up to date with the code.") is being used by many programmers as an
excuse to write no comments at all. It *is* true that meaningful,
specific comments do come out of sync with the actual code at one point
or another, but it is a risk and a responsibility that the developer has
to take, to ensure that synchronisation is maintained. The fact that code
maintenance means changing stuff, should not be a valid reason not to
document the original implementation(s) sufficiently.
--
Kristofer
Marc Rohloff [TeamB]
> The lines of programmer code per hour thread got me thinking about
> comments.
When I feel like putting in a comment I refactor my code. Often
improvements can be made by using better names or by taking out the
code you would have commented and putting in its own subroutine with a
name that describes what it does instead.
--
Marc Rohloff [TeamB]
marc rohloff at myrealbox dot com
Kristofer Skaug
>
> When I feel like putting in a comment I refactor my code.
Although I agree this often helps, it cannot always be the answer.
Even the best of method names cannot, in general, convey all necessary
details about valid inputs, special case outputs, error handling etc.
--
Kristofer
Mark Vaughan
news:40d955fd$1...@newsgroups.borland.com:
> Myself I tend to comment rather more than less, when in doubt. I
> have too many times noticed that "simple, obvious" things (to me)
> are far from obvious to a colleague who has to jump in and fix
> something in my code.
I've come to the same conclusion...but not necessarily to
assist my colleagues...it's frequently a matter of self-
protection. things that are blindingly obvious when you're
deeply immersed in a problem can become intractably opaque
15 years down the road :^D
--
Mark Vaughan
___________
Visit the Numerical Methods in Pascal web page at
http://www-rab.larc.nasa.gov/nmp/fNMPhome.htm
Dennis Landi
news:Xns951150C985...@207.105.83.66...
> "Kristofer Skaug" <ya.ierfgnf@thnxf.x> wrote in
> news:40d955fd$1...@newsgroups.borland.com:
>
> > Myself I tend to comment rather more than less, when in doubt. I
> > have too many times noticed that "simple, obvious" things (to me)
> > are far from obvious to a colleague who has to jump in and fix
> > something in my code.
>
>
> I've come to the same conclusion...but not necessarily to
> assist my colleagues...it's frequently a matter of self-
> protection. things that are blindingly obvious when you're
> deeply immersed in a problem can become intractably opaque
> 15 years down the road :^D
>
Yep, same here. Although 15 months is enough to completely bamboozle me!
I find a have a "two phase" commenting pattern. The first phase consists of
commenting to myself during development. But after the code is written I
find those comments superflous and/or cryptic.
I then (given the time) will start from scratch can go through and comment
each and every method as best I can. But here is what I find. You can be
"too close to the code" to really comment well. A little time (say, two
weeks) passed can also be helpful to get some distance.
-d
Kirk Halgren
news:40d991dc$1...@newsgroups.borland.com...
<SNIP>
> I find a have a "two phase" commenting pattern. The first phase consists
of
> commenting to myself during development. But after the code is written I
> find those comments superflous and/or cryptic.
>
> I then (given the time) will start from scratch can go through and
comment
> each and every method as best I can. But here is what I find. You can be
> "too close to the code" to really comment well. A little time (say, two
> weeks) passed can also be helpful to get some distance.
>
Excellent point.
Kirk Halgren
"Incrementing C by 1 is not enough to make a good object-oriented
language." -- M. Sakkinen
Loren Pechtel
wrote:
>I prefer to use the approach (and try to make sure I actually do) where
>I assume that the reader of the source (possibly me, years later) has a
>reasonably good grasp of the Delphi language, and only needs help (and
>extra comments) when
> - the code uses some obscure language construct
> - the code relies on a "friend" or similar device to operate
> - the context (such as thread context) is important
> - it is an ugly hack that is needed for some sort of historical reason
> - it depends on a certain version of some other software (e.g. db)
> - there is some kind of business rule which the implementation doesn't
>adequately explain
>
>What rules do you use in deciding what (and what not) to comment?
Yeah, as far as I'm concerned, well written code is generally
self-documenting. I'll document anything I don't consider fairly
obvious on reading the code. About the only time I've had trouble
with old code documented to this standard is business rule stuff--but
in general I didn't know the reason for the rule when I wrote the code
in the first place so there's not much I could have done about it.
Daniel Becroft
I have a feeling, judging by the feel of the other posts, that I do things the hard way. When
writing code, I do the following:
1) Create all the method/class skeletons, with method signatures, etc.
2) Comment these as interfaces, with PRE/POST conditions, parameters, return values, etc. These
comments are basically WHAT the method/class does, not HOW it does it. And, 9 times out of 10,
these comments get modified to enhance readability after the development is complete.
3) Create the UNIT test code, and comment this, with cases, what is tested, etc.
4) Go through each method skeleton, and complete the implementation. Comments here are placed
around while, for...do, repeat...until, if...else, and case statements.
Most of the time, it can be between 2 and 3 weeks between the steps #2 and #4. I end up with
approximately between 40-60% of my source lines as comments.
I also have a tendency to write 'self-defending' code, which could lead to slower code. Basically,
for the PRE conditions that have been defined for each method, these are confirmed, before reaching
the body of the method.
--
Daniel Becroft
; =================================
"Real computer scientists don't comment their code. The identifiers are so long they can't afford
the disk space."
"Blue sparks and white smoke, the two most expensive components of any electrical system, and once
used up will cost a fortune to replace."
Scout
[TeamB]" <"on request"> says...
> On Wed, 23 Jun 2004 19:18:51 +1200, Scout wrote:
>
> > The lines of programmer code per hour thread got me thinking about
> > comments.
>
> When I feel like putting in a comment I refactor my code. Often
> improvements can be made by using better names or by taking out the
> code you would have commented and putting in its own subroutine with a
> name that describes what it does instead.
>
when you're dealing with threads, a comment such as:
{ it is safe to call the vcl in this thread's constructor coz
we're still in the main vcl thread, subsequent calls must be
synchronized }
can save a whole bunch of pain down the road. It doesn't change the
design, it just acts as a warning.
I also comment things such as
insert into mytable (myfield1, myfield2)
select mynewvalue1, mynewvalue2 from rdb$database
left join mytable mt2 on mt2.myfield1=mynewvalue1
where mt2.myfield1 is null
This sort of thing is useful in IB upgrade scripts (to be run by the
isql command line tool) where you don't have any control over the error
handling, want to suppress the "duplicate" error in case the script is
run twice, and you have a sneaking suspicion that most sql script
kiddies would say WTF? when they see it.
There's no way that I know of to re-write this so a comment isn't
needed.
Is it obvious to you what it does?
How would you comment this?
Scout
Marc Rohloff [TeamB]
> Good point, and re-factoring is often a better idea than comments, but ...
I wasn't trying to say you shouldn't use comments, I was trying to say
that there are other things you should be trying first.
Craig Stuntz [TeamB]
> Yeah, as far as I'm concerned, well written code is generally
> self-documenting.
I see this claim a lot, and I think it misses an important point:
"Self-documenting code," when done well, can indicate *what* the code
does, but typically does a poor job of explaining *why* it does what it
does. In other words, yes, it's clear enough that the code
accomplishes a certain task by a certain algorithm even without
comments, but the algorithm may have been chosen because:
o Three other methods were tested with unacceptable performance
results, or...
o The Department of Labor regulations require payroll calculations to
proceed in a certain order, or...
o It is linked to a particular feature request from a certain customer.
(Etc.)
Many times while maintaining old code -- even code I've written myself
-- I've wondered why in the world it was written in a certain way,
although what the code did was quite clear. Good commenting can save a
lot of time in maintenance.
-Craig
--
Craig Stuntz [TeamB] . Vertex Systems Corp. . Columbus, OH
Delphi/InterBase Weblog : http://blogs.teamb.com/craigstuntz
Useful articles about InterBase development:
http://blogs.teamb.com/craigstuntz/category/21.aspx
Graham Stratford
Comments should not show "what" a section of code is doing (unless it is
rather complex), but "why" it is doing so. Of course, there is always a
place for comments at the head of units, functions, etc.
Also, every time I put in a comment, I try to think whether the code
wouldn't be better served with a function/procedure that accomplishes
the same goal. For example:
// Check to see if the user has permission
... my code here ...
might be easier to understand and maintain if it were put into a
function called
function TMyObject.CheckUserPermission();
Graham
In article <40d955fd$1...@newsgroups.borland.com>, ya.ierfgnf@thnxf.x
says...
> Scout wrote:
> >
> > What rules do you use in deciding what (and what not) to comment?
> Myself I tend to comment rather more than less, when in doubt. I have too
Kristofer Skaug
>
> You can be "too close to the code" to really comment well. A
> little time (say, two weeks) passed can also be helpful to get some
> distance.
Very true. It is indeed often when the rate of "big volume" code
production slows down and the preparations for "real life" take over,
that one can step back and look more objectively at the code (and start
itching :-) ). Most of the useful comments go in as I realize how
un-obvious something is, the 2nd or 3rd time around reading it.
--
Kristofer
Dennis Landi
wrote in message news:40da...@newsgroups.borland.com...
> Loren Pechtel wrote:
>
> > Yeah, as far as I'm concerned, well written code is generally
> > self-documenting.
>
> I see this claim a lot, and I think it misses an important point:
> "Self-documenting code," when done well, can indicate *what* the code
> does, but typically does a poor job of explaining *why* it does what it
> does. In other words, yes, it's clear enough that the code
> accomplishes a certain task by a certain algorithm even without
> comments, but the algorithm may have been chosen because:
>
> o Three other methods were tested with unacceptable performance
> results, or...
> o The Department of Labor regulations require payroll calculations to
> proceed in a certain order, or...
> o It is linked to a particular feature request from a certain customer.
>
> (Etc.)
>
> Many times while maintaining old code -- even code I've written myself
> -- I've wondered why in the world it was written in a certain way,
> although what the code did was quite clear. Good commenting can save a
> lot of time in maintenance.
>
Yes, you have to wonder about people who say well-written code is
self-documenting. I use to get this from VB programmers (I had to manage).
I think their is just a chasm between the kind of code people write and the
kind of software projects people develop. If the bulk of one's code doesn't
extend past the GUI event-handlers then I dare say it is easy enough to see
the operational context of the code *and* the design context.
But for other projects that perhaps don't have a GUI at all, or do not
conform to a design context like, say, COM or CORBA or Web Services etc.
then the entire code is a creature of the underlying design philosophy upon
which the code is built. Needless to say these designs/philosophies should
be documented elsewhere but there will also need to be appropriate comments
in the code. *Especially* if well-written, because that means the design
philosophy will be atomized in many short, sharp methods with few lines of
code.... One could let's one successor spend his life in the debugger so he
can build his own trail of bread-crumbs, or you could just give him a clue
by holding up big traffic signs.....
-d
Loren Pechtel
<gstra...@das.ca> wrote:
>Also, every time I put in a comment, I try to think whether the code
>wouldn't be better served with a function/procedure that accomplishes
>the same goal. For example:
>
>// Check to see if the user has permission
>... my code here ...
>
>might be easier to understand and maintain if it were put into a
>function called
>
>function TMyObject.CheckUserPermission();
I never thought of it that way before but I tend to do this
also.
Mike Swaim
> Yeah, as far as I'm concerned, well written code is generally
> self-documenting.
Only if it's obvious what you're trying to do, and the algorithm that
it uses. If neither is the case, then you really should provide some
documentation.
--
Mike Swaim sw...@hal-pc.org at home | Quote: "Boingie"^4 Y,W & D
MD Anderson Dept. of Biostatistics & Applied Mathematics
mps...@mdanderson.org or msw...@odin.mdacc.tmc.edu at work
ICBM: 29.763N -95.363W|Disclaimer: Yeah, like I speak for MD Anderson.
Kirk Halgren
wrote in message news:40da...@newsgroups.borland.com...
>
> > Yeah, as far as I'm concerned, well written code is generally
> > self-documenting.
>
> I see this claim a lot, and I think it misses an important point:
> "Self-documenting code," when done well, can indicate *what* the code
> does, but typically does a poor job of explaining *why* it does what it
> does. In other words, yes, it's clear enough that the code
> accomplishes a certain task by a certain algorithm even without
> comments, but the algorithm may have been chosen because:
>
> o Three other methods were tested with unacceptable performance
> results, or...
> o The Department of Labor regulations require payroll calculations to
> proceed in a certain order, or...
> o It is linked to a particular feature request from a certain customer.
>
> (Etc.)
>
> Many times while maintaining old code -- even code I've written myself
> -- I've wondered why in the world it was written in a certain way,
> although what the code did was quite clear. Good commenting can save a
> lot of time in maintenance.
>
> -Craig
Another way those details may help is to explain what the developer was
thinking when he chose the particular means of doing something. Sometimes
I'll look at code I wrote a while back, and know a much better way to do the
same thing. Without the explanation I would be more reluctant to change the
code, especially if it was written by someone else.
My main job these days is data validation coding/testing, and I always just
copy the whole validation rule into the top of each function. As I
test/debug, and over time the rules do change, I find being able to read the
rule without going to the database very helpful.
Kirk Halgren
"Inventing is a combination of brains and materials. The more brains you
use, the less material you need."
--Charles Franklin Kettering, inventor of the battery ignition and the
electrical starter.
ozbear
<msw...@odin.mdacc.tmc.edu> wrote:
>Loren Pechtel wrote:
>
>> Yeah, as far as I'm concerned, well written code is generally
>> self-documenting.
>
> Only if it's obvious what you're trying to do, and the algorithm that
>it uses. If neither is the case, then you really should provide some
>documentation.
>
Quite true. A book or web reference is sometimes all that is required
that points to the relevent guts behind an algorithm. I sometimes
also include why some other algorithm wasn't chosen. Someone else
reading the comments can then see why and skip all "why didn't he
use xxxx instead" or, if the conditions have changed such that a
discarded algorithm is now a superior solution, adopt a different
one.
Oz
--
A: Because it fouls the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing on usenet and in e-mail?