On Sun, Mar 16, 2008 at 09:23:51AM -0700, Paul G. Allen wrote:
8 spaces is too much, it takes too much space on the line. It forces the
eye to move and look around the page too much. 2 is too few as it does not
separate the indented structure enough from the surrounding structures. 4
seems to be optimal as it provides good separation, does not force a lot of
eye movement, and does not take up too much space on the line.
(Ref.: McConnell, Steve; Code Complete; Microsoft; <http://www.cc2e.com/>)
But, it's just a bunch of arbitrary numbers. Why should I care what Steve
thinks is "too much" or "too little" spacing. Other people obviously have
differing opinions. Change the numbers to different values, and you will
get a different set of people arguing loudly that they are absolutely
right.
This is impractical for a few reasons. In actual practice, SDDs don't
often get written.
Which, BTW, I would argue is a good thing. Except for programs that are
very similar to ones that are already written, the design isn't known or
understood until the program has at least been partially written. You end
up with an SDD that describes something different than the code. At least
when information is in comments, it is slightly more likely to be updated
as the code is updated.
It is reasonable to have a separate document describing how to use a piece
of software, whether that be for the end user, or to another programmer on
how to use a library.
Each class, method, file, function, or module should have a comment header
describing what it's supposed to do. (Not what it does, but what it's
*supposed* to do.) It should have a list of input parameters and exit
parameters (returns).
I have so rarely seen a list of parameters that was useful, I now actively
argue against putting them in list form. Most of the time, they end up as
an English description of the types of the variables. I would much rather
see a piece of prose that mentions the arguments. I think people like the
lists because they don't have to think about it.
I think a lot comes from people writing their comments to the wrong
audience. Really, there need to be two comments for a function. In
languages with separate declarations, this works well:
- One comment should be for the person who wants to use the function.
The should not care how it is implemented, but what it does and how
they should be using it.
- The other comment, which should be near the function, should be written
for someone who wants to understand the implementation or modify it.
It should be assumed this person is fluent in the language, and should
describe the stuff that isn't obvious.
At times I've seen them (and written them) with references to calling and
called functions/methods, but these days a code browser (and many IDEs)
will tell you that. On occasion the method/function itself may need a
comment here or there to explain why something is done that may not be
obvious (e.g. - some quirk of the machine it was written for causing the
engineer to write some little piece of code that may not normally be
there). The code itself should be self-documenting such that a lot of
comments throughout is not necessary.
A good rule is that a comment should never describe anything that is
specified in the code. The programming language is a more exact way of
describing these things.
With code that is maintained by a team of engineers, comments as to who
changed what, when, and why are necessary, and in most cases, mandatory.
Often a simple changelog at the top of the file is not enough to adequately
explain the changes made.
Or, get a [EMAIL PROTECTED] revision control system. Any comment, anywhere,
that
describes a change or it's purpose tells me that the revision control
system is broken. If other people don't have access to your revision
control system, get a distributed revision control system.
Cluttering the code with information that doesn't matter to the reader just
makes it difficult to read. A decent system will have a "blame" or
"annotate" command, and it is very easy to figure out what change put a
piece of code in place, and read a detail of the description. I can then
also look at what it was changed from, instead of just the partial
information of what it is like now.
We've actually recently just had to add an additional requirement to a
contractor to forbid them from putting these kinds of comments in code.
David
--
[email protected]
http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
