Re: Spoilers in Tech Docs!
You start with a "Header" that documents what the procedure does,
Absolutely essential while writing Java, but if you go quite a bit further you'll have something that anybody can understand and, better yet, YOU will understand if you need to tweak it in a year or five.
- The class-level description needs to say what the CLASS is intended to do, no more and no less, though it may also be a good place to describe the meanings of any public constants
- The method level descriptions can be quite brief. They should give guidance about when to call them, unless they're a simple getter or setter, but should not paraphrase any of the @param annotations
- This documentation must be run through javadoc and read to check that it makes sense
If you don't do all the above BEFORE you write more than than a skeleton class and methods then (a) you probably haven't thought the class design out properly and (b) for sure you'll piss off future developers.
The same goes for writing C except the the 'class' level stuff goes at the top of the source file and you need to check what's in your comments by running the code through your chosen documentation tool.
Last but not least, if the class or function package does anything thats even slightly complex write a test harness and a set of regression tests that get put into version control and/or backed up with thre code it tests. A PHB will tell you this is not necessary and/or a waste of time but IME he will be very wrong. A well-considered set of regression tests (covering simple usage, edge cases, and as much misuse as you can imagine) will save a LOT of wasted time and swearing. The test harness need merely take a line such as
methodname param1 param2 ... # comment saying what you expect
and split out the method name and parameters into an array of, say, strings and ints before executing an if.. then.. else.. totem pole which calls all the methods and displays all results interspersed with a listing of the test script. Dead simple: no conditionals needed because you can simulate that by the order of method calls in it.
If you're clever, you'll put all the script reading, parsing and printing into a driver structure that can run scripts against plugins that are specific to the class being tested and add something that compares test output with a set of expected results: a regression test pass is when the comparison produces no output.