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