If I don't do this, when I come back to the code an hour later I have no idea what its supposed to do or why I wrote it. I'll also usually add an explanation, like "3 is bad number of args because..."
> 44. Funny names are funny, you can always change them later.
This one drives me crazy, I hate when people use something like "x" or "habberdasher" instead of something functional like "newspapers"
Many people write comments which are often nothing more than a really obvious transliteration of the code to English "foobar += 3; // Add 3 to the foobar".
These comments add little to nothing and often become worse than useless when they fall out of date and you end up with a cryptic "foobar += 7; // Add 3 to the foobar"
I find it helpful to imagine a codebase guru, someone who not only wrote the thing but has had years of experience maintaining and teaching to others... and the comment writes down what they would say if you asked them about it.
The guru wouldn't say 'adds three to foobar', they'd tell you about how the number used to be the obvious value of two but then the database choked when the boss was trying to store their golf scores in it, because foobar controls the whatzanits and there can be a race that requires it to have room for one extra. The guru would tell you _why_, and that's what a better comment will do.
Students of programming are often just writing what they're told to write. They don't necessarily have a strong grasp on the why, especially not a deep contextual grasp.
using namespace std; // using namespace standard
add $1, $2, $3 #add some stuff.
I think the point that the tweet is trying to make is that if you comment, you should explain why you are doing something instead of saying what you are doing. The latter is already written there, in code.
# authenticate user
Good coding means two things, in general:
* There is no more understandable comment than no comment needed.
The code should explain _what_ it is doing as close as possible in words such that any programmer, including you, can read the code and understand what it is doing.
Bad: sum = a.length + b.length
Good: totalNumberOfGoodProducts = exceptionalProducts.length + acceptableProducts.length
* Comments should be the exception for _why_ something odd is happening.
Bad: if(r == 42) return; // Nothing happened.
Good: if(ioReturnCode == 42) return; // Ignoring code 42, an undocumented value and seems to be a "no operation happened." We'll retry again later in the code.
Think of writing a comment as a failure of your ability to write good code - we all fail from time to time but we asipre to do better over time.