On Thu, Mar 29, 2012 at 02:52:17PM +1300, James Miller wrote:
[...]
> Exactly my point. There is a line between "code must be self
> documenting" and "I need to read the code to understand what this
> does". Self documenting code is more about removing the cognitive
> stress of reading code. Actual documentation needs the whys and
> wherefores about everything.
I would argue code comments should do the same.
This reminds me of when I was working as a teaching assistant in
college. In class, the lecturer drilled it into the students that they
need to comment their code, the more comments the better. So some
students handed in code that looked like this:
// Define a function
int myfunction(int y) {
// Loop from 1 to 10
for (int i=0; i < 10; i++) {
int x; // declare a variable
x = i; // set x to 0
// If condition is satisfied
if (x*2 + y*3 - 7 < 9) {
y--; // decrement y
}
}
// Return result
return y*3 - x;
}
Next class, the lecturer had to tell them that comments are not for
restating what's already obvious from the code; they're intended to
explain what *isn't* obvious, like what's the purpose of the function,
what's the meaning behind the if-condition, etc..
I had my laugh then, but now I'm working in the industry and sometimes I
see code like this:
int somePoorlyNamedFunction(int y) {
int x = 123;
if (y*7 - 4*x + 9 < 16) {
// Fix bug of wrong result
return 19-x;
}
return 17-y;
}
and I start wondering where people bought their diplomas from...
> std.string is a brilliant example, with a list of 68 functions at the
> top, and a total of 89 anchors (presumably just overloads), there is
> no easy way to quickly find a function for a purpose. You have indexOf
> - a searching function - next to insert - a manipulation function -
> next to isNumeric - a property testing function. Each of those
> functions are "self-documenting" but that doesn't mean they wouldn't
> benefit from categorization.
[...]
Yikes!! I think my next doc-related pull request may very well have to
be std.string... :-/
T
--
"No, John. I want formats that are actually useful, rather than
over-featured megaliths that address all questions by piling on
ridiculous internal links in forms which are hideously over-complex." --
Simon St. Laurent on xml-dev
