Re: Encouraging good comments Which language ?

[marbux <marbux@...>]

As I see it, there are a lot of variables deserving of consideration
when deciding what level of detail code comments should have. E.g.,

Who is the audience and what are their skills? If you are writing code
examples for novices learning to program, you'll need to wrap an
entire book of comments around the code. At the other extreme, if
you're the only person who's ever going to touch the code, you have
absolute freedom to comment or not comment as you desire.

How counter-intuitive is a given block of code? If it's part of
spaghetti code with dozens of bug-fixes and work-arounds in it, others
who have to work with the same code would probably appreciate you
erring on the side of over-documentation.

-- Would metadata assist in finding your way back to the code if
someone needs to later? I do my development work on a system that has
Isys Desktop Search installed. I find that adding classifying metadata
in code comments an incredible aid in code recycling.

Undoubtedly there are other factors as well. But bottom line, I don't
think there is a one-size-fits-all answer to how prolific comments
should be.

Best regards,

Paul