??? 05/20/10 09:08 Read: times |
#176055 - Always document what the code is doing or the weather Responding to: ???'s previous message |
<irony>
Golden rule for commenting: Always describe what happens in multiple ways, to make sure that a dense reader in some way will pick up the facts. // Main function, where the program will start. int main() { int i,j,a,z,tmo,gpo,gpl,ttf93; // Useful variables. a = 0; // Clear a. // Iterate 10 turns for (i = 0; i < 10; i++) { P1 |= 1 << 3; // Set bit 3 of P1. for (j = 0; j < 500; j++) ; // Magic delay. P1 |= 1 << 4; // Set bit 4 of P1. for (j = 0; j < 500; j++) ; // One more magic delay. P1 &= ~((1 << 3) | (1 << 4)); // Clear bit 3 and 4 of P1. for (j = 0; j < 453; j++) ; // Yet more magic delay. } for (;;) ; // Infinite loop. } It is also important that the comments "flows" with the source so that they generate the correct "gray" feeling when looking at the code with a bit blurry eyes. For best effect, this can be combined with a bit more creative indenting (or non-indenting for the advanced developer). Describing "why" something is done should always be avoided - this may make the new kid on the block manage to upgrade an application without introducing any new bugs, and that is never a good thing when it gets time to discuss salaries. All comments should concentrate on "what" or the weather outside or what the girl in the next office cubicle is wearing. </irony> |
Topic | Author | Date |
When comments go wrong | 01/01/70 00:00 | |
Always document what the code is doing or the weather | 01/01/70 00:00 | |
do you have some examples of that? | 01/01/70 00:00 | |
I've never seen anything like that ... | 01/01/70 00:00 | |
Do it like a pro. ;) | 01/01/70 00:00 | |
the dubious value of comments | 01/01/70 00:00 | |
RE: not subject to any scrutiny of the compiler | 01/01/70 00:00 | |
limited vocabulary | 01/01/70 00:00 | |
dubious | 01/01/70 00:00 | |
Please remove baby from bathwater before disposal! | 01/01/70 00:00 | |
Good selection of symbol names helps a lot | 01/01/70 00:00 | |
variable/function names can be misleading too | 01/01/70 00:00 | |
RE: the word Andy will be so kind to supply... | 01/01/70 00:00 | |
Well | 01/01/70 00:00 | |
Dodgy premise | 01/01/70 00:00 | |
That's no fun. | 01/01/70 00:00 |