Writing Code Documentation

First line of description
The first sentence of each <Desc> section should be a summary sentence, containing a concise but "complete" description of the declared entity. This sentence ends at the first period that is followed by a blank, tab, line terminator or a "".

This first line is used in different summaries, but we also feel this is a nice convention, letting your readers as quickly as possible recognize what the entity is, whether it is relevant to their purpose.

We highly recommend that you write this single line description before (in time) you write the implementation, or at least immediately afterwards. We find that writing a concise single line description of the method/routine etc before writing the implementation sort of tests whether the method/routine will be 'coherent'. (A good method/routine should typically only do one thing and do it well.) We also find that this helps giving the method/routine a good name, which we find very important.


HTML generated by Time2HELP
http://www.time2help.com