[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