Level Extreme platform
Subscription
Corporate profile
Products & Services
Support
Legal
Français
Code Documentation
Message
From
07/12/2003 13:45:32
 
 
To
07/12/2003 13:09:59
General information
Forum:
Visual FoxPro
Category:
Other
Miscellaneous
Thread ID:
00856259
Message ID:
00856714
Views:
24
> (c) It is written before the code and thus is a statement of intent, not
> documentation of what is actually happening

What's actually happening (barring corrupt indexes and things like that *g*) is already written down precisely: in the form of source code statements. What is not always apparent from the code is what is supposed to accomplish, namely the intent. For example, when a statement or command has several consequences (affects program state in more than one way) then it is not always obvious which ones of these consequences are intended and which ones are incidental; also, the manner in which these consequences are used is not always apparent. That is why code sometimes needs to be supplemented with comments for the benefit of human readers. In fact, I would consider such comments an inseparable, necessary part of good source code.

Comments that state what's happening are generally redundant and cause more harm than good. See Steve McConnell's Code Complete for a more comprehensive treatment of this subject (I cannot give specific references as I don't have access to the book ATM).
Previous
Next
Reply
Map
View

Click here to load this message in the networking platform