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

Back to Subject List

Old thread has been locked -- no new posts accepted in this thread
???
08/17/08 10:30
Read: times


 
Msg Score: +2
 +2 Good Answer/Helpful
#157529 - Documenting "why" and not so much "how"
Responding to: ???'s previous message
But an important thing to note about this, and so very often forgotten:

Comments should probably spend more time on describing why a program does what it does, than documenting how.

By reading the code, a competent developer should be able to pick up the "how". But it may be impossible to pick up the "why", since that may have been a customer requirement, but just as well a planned stepping stone for some future improvements that for some reason never got implemented.

Another reason for documenting the "why" is that a problem may later be found. Without knowing the why, it is hard to know if it is ok to take one step back and reengineer with a different solution, or if the problematic solution must somehow be patched into compliance.

When using a high-level language - relatively speaking of course, since I'm thinking about C :) - symbol names can be chosen to greatly help with describing how something works. But an imperative procedural language are not well suited for describing the reasons behind any variable assignments or function calls.

List of 17 messages in thread
TopicAuthorDate
Amnesia ( =loss of memory)            01/01/70 00:00      
   Only a problem when...            01/01/70 00:00      
   A matter of practice            01/01/70 00:00      
      Two replies...            01/01/70 00:00      
         All normal            01/01/70 00:00      
         Plus....            01/01/70 00:00      
   It only gets worse...            01/01/70 00:00      
   Ah the benefit of code re-use            01/01/70 00:00      
      A good idea..            01/01/70 00:00      
   memory and professional carrier            01/01/70 00:00      
      Documenting "why" and not so much "how"            01/01/70 00:00      
         this is not the point            01/01/70 00:00      
            Art of knowing what you will need in future..            01/01/70 00:00      
               After 20 years 8051 assembler,            01/01/70 00:00      
                  c'mon, don't be shy            01/01/70 00:00      
                  Learning typing            01/01/70 00:00      
                     Often fast but hard to multitask            01/01/70 00:00      

Back to Subject List