[EMAIL PROTECTED] wrote:
You'd think KISS principle would make people embrace the Linux coding style....
(80 column lines & 8 space indents)
Instead they cringe!
Now *I* cringe when I hear about 2-3 space idents and 130 column lines.
Anyone ever seen a case where lotsa little functions *wasn't* ideal and *very*
nice? 8 space tabs/80 columns forces you to chop your problem into little bite
sized functions!!! I love it!
I didn't notice anyone in this thread mentioning the reason for
indentation in the first place (maybe someone did, but I didn't see it).
The reason for it is readability, not to enforce structure. Structure
should come before the first piece of code is ever placed on the page
(or in the editor).
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/>)
In reference to the blog mentioned elsewhere in this thread. There is a
statement in the blog regarding moving comments (metadata) into the
design documents. This is impractical for a few reasons. In actual
practice, SDDs don't often get written. In addition, a programmer or
engineer coming in is not often likely (even if given the opportunity)
to read it. Second, to have to take you eyes off the code to read a
reference manual in order to understand the code you're looking at is a
huge waste of time.
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). 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.
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.
PGA
--
Paul G. Allen, BSIT/SE
Owner, Sr. Engineer
Random Logic Consulting Services
www.randomlogic.com
--
[email protected]
http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
