The return value has to be documented per our coding standards and the project contract (what we agreed we would provide to those paying us). In this case, I am changing (and improving) regular comments to doxygen comments (http://www.doxygen.org), which will be used to produce documentation of the code which will be delivered to our customer. There is no choice about whether to comment it or not.
-Jean >-----Original Message----- >From: [EMAIL PROTECTED] >[mailto:[EMAIL PROTECTED] On Behalf Of Jason Teagle >Sent: Monday, October 17, 2005 1:20 PM >To: [email protected] >Subject: Re: [msvc] Documenting code > >>For instance, if I have a function named F1(), and its return >value is >>the return value from function F2(): >> >>bool F1() >>{ >> // do some stuff >> return F2(); >>} >> >>How should that be documented? > >*** Personal opinion disclaimer *** > >I think it very much depends on the situation - in this case, >how F2 is named. If it's got a more meaningful name than just >"F2" <grin> then in theory, it shouldn't need a comment - it >should be obvious. > >I feel that you should only comment what something does if >it's not immediately obvious, like why you have a for loop >that starts at 1 rather than 0, or something subtle like that. >Similarly, you should only document parameters to or from a >method if their use requires some special consideration beyond >the obvious name of the parameter. > >Thus, in your case I'd say you really don't need it - unless >you want to say why you bothered to put a wrapper around >another function that does nothing except pass it on {:v) > >-- >Jason Teagle >[EMAIL PROTECTED] > > > >_______________________________________________ >msvc mailing list >[email protected] >See >http://beginthread.com/mailman/listinfo/msvc_beginthread.com >for subscription changes, and list archive. > > _______________________________________________ msvc mailing list [email protected] See http://beginthread.com/mailman/listinfo/msvc_beginthread.com for subscription changes, and list archive.
