[sldev] Doxygen & Comments

John Hurliman jhurliman at wsu.edu
Thu Jun 7 11:55:27 PDT 2007


Dzonatas wrote:
> By no means is that meant negative, but it simply a reflection. In my 
> experience, C++ is a way to speak with a diverse population of 
> programmers even when there is no common non-program language for 
> which the two programmers may use to effectively communicate. I merely 
> suggest an accelerated means by reasonably attempt to pave the way on 
> beautiful virtual roads with nice lush un-littered scenic green grassy 
> fields.

While we are talking about experiences I will throw mine in. When 
contracted to write software for international teams I've always been 
asked to go the extra mile on software comments and documentation, 
because the code is written in English. I might name a variable 
"increment", but never "増分" (or whatever). The variable name is an 
extremely terse wording that usually doesn't provide enough context for 
anyone to understand what is going on without looking at the rest of the 
code, and if the rest of the code does some non-obvious things like a 
lot of pointer arithmetic or has bugs in it, you have a communication 
breakdown. Documenting what code is supposed to do and then verifying 
that it actually does that can go a long ways towards finding problems. 
Beyond documenting the purpose of something, documenting usage and 
parameters can be either helpful or necessary if you have functions that 
aren't immediately obvious what they are used for or what the parameters 
and return values are used for.

John Hurliman


More information about the SLDev mailing list