← Back to team overview

kicad-developers team mailing list archive

Re: Latest SVN commits.


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

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!