AJCopland wrote:
@falemagn
Yeesh, yuck and no! :-x
That kinda code is itself a comment as it's a simple assignment,
Wasn't that the point? Self-documenting code, indeed. You said it yourself. :-)
And yes, I admitted it was an extreme case, just to show the point. That doesn't mean that other, not so extreme cases, don't exist. In fact, read on...
but what are you going to use it for and what is the number 2 representing? Bad commenting.
That was all that had to be commented, an assignment. 2 represents 2, that's all. If I wanted 2 to mean something else than just 2, I wouldn't have used 2, but rather a named constant: again, self-documenting code. In fact, read on...
/* integer variable 'aIdx' is used in the following loop to
iterate through mini-game actors updating them. Has initial
value of 2 because first 2 entries are player 1 & player 2
*/
int aIdx = 2;
for( ; aIdx < numMiniGameActors ; ++aIdx )
{
MiniGameActors[aIdx]->update(deltaTime);
}
That is a mildly spurious example, but it IS still a more valid example. Someone else will read your code, probably you, in 6 months time and be glad that you documented why you used the value 2. Also renamed 'a' to 'aIdx' to more clearly indicate that it is used as an index.
Problem is, commenting is superfluous in the above code.
1)
"integer variable 'aIdx'" - the name of the variable is clear as it's clear it's an integer, no need to spell those in English.
2)
"is used in the following loop to iterate through mini-game actors updating them" - the fact it's a
loop it's pretty self evident, the fact it's looping through
mini-game actors is evident too, by the name of the MiniGameActors array that is being indexed, and the fact that those actors are being updated is also obvious, for the mere fact that the
update() method is being invoked on them.
3)
"Has initial value of 2 because first 2 entries are player 1 & player 2" - so then, if that's what 2 means, why not state that explicitely
in the code? You could have done it like this:
enum { numPlayers = 2; }
for(int aIdx = numPlayers; aIdx < numMiniGameActors; ++aIdx)
{
MiniGameActors[aIdx]->update(deltaTime);
}
There, no need to write any comment, the code is indeed self-documenting. In fact, looking at this code for the 1st time I can say that this is a loop going through mini game actors so that they are updated taking into consideration the time elapsed since last time they were updated. There are 2 (human?) players in the game which are considered to be "actors" too, for the sake of code simplicity, but that don't need to be updated, as they are not controlled by the AI, and those 2 players are the 1st and 2nd element of the MiniGameActors array, therefore we skip them when updating the rest.
You're never writing code just for yourself, you're writing code for you in 6 months time as well. Not only that but it's good practice to comment why you did something so that when you are working on a group project you don't forget to do it for others who might be less experienced than you. (I see this lack of *why* comments everyday on the current project, it slows down work and is poor coding style).
I'm a professional programmer, highly rewarded for my work too, been programming since I was 6. Don't assume I don't know what I'm talking about, thanks. ;-)
