kicad-developers team mailing list archive

[Philip Pemberton <ygroups@...>]

Wayne Stambaugh wrote:
> I think Linus said it best in the "Linux
> Kernel Coding Style" when he said "NEVER try to explain HOW your code
> works in a comment: it's much better to write the code so that the
> _working_ is obvious, and it's a waste of time to explain badly written
> code".

I'd be inclined to agree with that -- comments should explain WHY, not HOW. 
That is, I'd rather see this:

/**
* V2.1 hardware returns an incorrect byte count (see Hg 2f924abcdef and
* Bugzilla #2931). This code corrects the byte count, and stops the buffer
* copy from segfaulting.
*/
if (HardwareVersion == 210) byteCount--;

Than this:

// Decrement byte count if V2.1 hardware detected, see XYZ-3021-A
if (HardwareVersion == 210) byteCount--;

On the grounds that #1 tells me exactly what I need to know, and where to go 
for more information on the issue in question. #2 just says what the code 
does, and if I don't have a copy of XYZ-3021-A (whatever that is), it's no 
help at all. The only thing that sort of coding is good for is annoying 
maintenance programmers...

You could argue that the guy working on the code might not be able to access 
the source code repository or Bugzilla, but in OSS/FS, that's going to be the 
exception rather than the rule.

There is a point where you can be /too/ verbose, and massive comments that 
fill the entire screen really are annoying (especially when you're using an 
editor that can't do block-folding) but I'd argue that big chunks of 
completely undocumented code are far worse.

I'd love to do some actual coding work on Kicad, bugfixing, whatever. I was 
going to say "feature additions" but other than reworking the basic component 
libraries to use more standard symbols (which AIUI other people are working on 
already) I honestly can't think of any!

Thanks,
--
Phil.
ygroups@...
http://www.philpem.me.uk/