??? 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. |
Topic | Author | Date |
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 |