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

Back to Subject List

Old thread has been locked -- no new posts accepted in this thread
???
07/20/09 10:46
Read: times


 
Msg Score: +1
 +1 Good Answer/Helpful
#167591 - Reasons and assumptions
Responding to: ???'s previous message
One thing that is most often forgotten when documenting - and which is impossible to convey with variable names - is reasons.

When you pick up code 6 months or maybe 6 years later, you want to know why a block of code does something. General C knowledge should be able to tell what the code does, but it may be almost impossible to deduce the reason.

I can see code having a delay of 200ms. But I can never manage to figure out why 200ms was selected.

I may be able to see code light a specific LED, but I may not be able to figure out why. Maybe the LED information has to match something in a user manual, but without corresponding information in the code, it will impossible to know.

I can see code specify a 20 character large array for text input, but how do I know if 20 is a good size?

How was the size of a UART receive ring buffer decided? Based on what maximum baudrate? Based on what maxmimum poll interval? Based on a knowledge that the received data may arrive quickly but always in short burst, giving the processor time to catch up?

Reasons and assumptions are the absolutely most important comments, since it is so hard - or impossible - to reverse-engineer this information from the code even if each symbol name is 30 characters long.

List of 24 messages in thread
TopicAuthorDate
Keypad interface problem: My code not working..            01/01/70 00:00      
   Check in a simulator            01/01/70 00:00      
      RE:            01/01/70 00:00      
         Care for details            01/01/70 00:00      
            Formatted code            01/01/70 00:00      
            RE: i dint check the bounce            01/01/70 00:00      
               Bounce vital to think about            01/01/70 00:00      
                  Do document            01/01/70 00:00      
                     re: documentation prob            01/01/70 00:00      
                     Fixing prob:            01/01/70 00:00      
                        Did you search?            01/01/70 00:00      
                           RE: the search tool here is not the most powerful            01/01/70 00:00      
                           Karas's Keypad Scanner Code In C - detabbed            01/01/70 00:00      
                     Properly documented code            01/01/70 00:00      
                        Reasons and assumptions            01/01/70 00:00      
                           Per, you implied, but did not say            01/01/70 00:00      
   dangerous loops            01/01/70 00:00      
   code???            01/01/70 00:00      
   RE: now am modified my code            01/01/70 00:00      
      How to post legible source code            01/01/70 00:00      
         unfortunately, that does not add comments            01/01/70 00:00      
         re: thanks now i got how to insert code            01/01/70 00:00      
   Scanning Keypad            01/01/70 00:00      
   How to scan Keypad            01/01/70 00:00      

Back to Subject List