Re: Real world coding standards implementation feedback
On May 20, 5:42 pm, Noah Roberts <n...@nowhere.com> wrote:
James Kanze wrote:
On May 20, 12:06 am, Jeff Schwab <j...@schwabcenter.com> wrote:
Phlip wrote:
daniel.coudr... wrote:
we are in the process of selecting / devising a C++ coding
standard to use internally to our company our be able to
provide feedback to our customers about.
How about "every line of code, every branch, and every
argument shall have documenting unit tests"?
Define "documenting unit tests". A unit test doesn't
document anything. And passing a unit test doesn't prove
readability. Unit tests are an essential part of the
development process (and given the possible standards cited
by the original poster, and the environment from which they
come, I'm rather certain he's aware of this). But you still
need guidelines for such basic things as naming conventions,
indentation, file organization...
Another agile development paradigm. The unit tests, since
they cover the entire API, serve as documentation for said
API.
And that, of course, is just bullshit. A trumped up excuse for
not writing the documentation. Unit tests are unit tests.
Documentation is documentation. They serve two different roles,
and are two very different things.
If I want to know how a particular class is meant to be
used, I can look at the unit tests. Of course, the unit tests
often need some sort of documentation of their own.
And of course, trying to figure out how what the exact pre- and
post-conditions of a function are from unit tests is a herculean
task. Where as one line of English text may express it clearly
and concisely.
I don't totally disagree with the reasoning. Quite often the
best way to learn how to use something is to see it used.
That's something else. Although you'd certainly want your unit
tests to be more complete than just a simple example.
That's what the unit tests do. I don't agree though that it
works in all cases or for all people. Thus we do both unit
tests AND doxygen AND uml AND comments where something is
weird.
Exactly.
If I have to maintain the code, I'm definitely going to look at
the unit tests---I'll almost certainly have to expand them. If
I'm just a user, however, I shouldn't have to look at any code
(except maybe, as you say, some simple examples---but most
classes should be simple enough that you don't need those).
--
James Kanze (GABI Software) email:james.kanze@gmail.com
Conseils en informatique orient=E9e objet/
Beratung in objektorientierter Datenverarbeitung
9 place S=E9mard, 78210 St.-Cyr-l'=C9cole, France, +33 (0)1 30 23 00 34