This repository has been archived by the owner on Apr 6, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 24
Documenting guidelines
virmitio edited this page Jun 27, 2011
·
2 revisions
- As a general rule, please use something that at least resembles proper english grammar and spelling. This both avoids the confusion and consternation of other developers and prevents violent outbursts from the testers trying to follow the documntation.
- It is highly recommended that all in-source documentation be done as well-formed XML-comments. If you don't know how to use these, please use this and this as references.
- Please try to supply information about what the general purpose of the class is. Why do we have this class at all?
- What other classes and/or projects depend upon this class?
- What other classes/projects does this class depend upon?
- Please provide as complete a description as possible of what the method is intended to do.
- List each parameter, and what effect that parameter should have upon the results. If a parameter should have no effect, explicitly say so.
- List any pre-conditions or expectations for the method and the parameters being passed to it. What is it we assume will be passed to the method?
- List any post-conditions or after-effects of the method. Does the method change one of the parameters? Does the method make changes somewhere besides the parameters and the return value? For example, should the world burst into a ball of fire after we call the method 'void Sun.explode()'?