Email: Password: Remember Me | Create Account (Free)

Back to Subject List

Old thread has been locked -- no new posts accepted in this thread
???
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>

List of 16 messages in thread
TopicAuthorDate
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      

Back to Subject List