To me, "keep it short, simple, but always
explain your intentions in prose" need to be the guiding
lights for programmers.
It was instilled in me early on by my one and only mentor that
someone that comes along later may have no idea what my code is
doing. So comment. Even when it might be self-explanitory, comment
anyway. This was on TOPS-10 back in the early 80's, usually MACRO-10
although I dabbled in ALGOL, SNOBOL, FORTRAN, etc.
When I look back at my own code, I can read the comments as the
plot-line, so to speak, and the code itself just follows along.
I have noticed a lot of newer programmers these days that say
(paraphrased): "Good code will explain itself" as a reason not to
comment. Mostly C++ and Java programmers.
I call bullshit on that. Not commenting is lazy. There's no reason
NOT to comment.
Most of my stuff has more comments byte-wise than real code.
Something I wrote just yesterday as part of a much larger project: // remove the UTF-8 BOM at the beginning of a line of text.
char bom[] = { 0xEF, 0xBB, 0xBF, 0 }; //
UTF-8 BOM void remove_bom(char *str) { if (strncmp(str, bom, strlen(bom)) == 0) { //
can we find the BOM at the beginning of the line? strcpy(str, str + strlen(bom));
// yup, kill it. } }
While that is definitely self-explanitory, I just can't help
myself - and no, don't comment on my brazen assumptions of string
length, or the fact that I assume it's UTF-8 - I've taken care of
all of that elsewhere... ;)