Re: Coding Standards
On Sep 5, 3:41 am, Phlip <phlip2...@gmail.com> wrote:
James Kanze wrote:
[...]
More importantly, assertions and unit tests aren't part of the
documentation.
They have majorly overlapping and complementary roles.
They have distinctly different roles. In particular, you can't
write a single line of code (unit test or implementation) before
you know what the function should do, and you don't really
"know" anything until you've written it down. For some very
simple functions, just the function name may be sufficient, but
99 times out of a 100, you'll need more. Some of that more can
be expressed within the language---if the return type is int,
for example, there is an explicit post-condition that the return
value won't be 1.5. But there are still a lot of things that
cannot easily be expressed, even taking assertions into account.
And as it currently stands, C++ has no mechanism for specifying
the assertions in a way that the user can see them. (What we
really need, of course, is some sort of system which converts
the documentation into a header file, rather than things like
Doxygen, which do the reverse. Something like ESC for Java
would be nice as well.)
You might be different, but I rarely go from reading a new API's
documentation to typing in its first function. I keep searching until I
locate some good sample code. It almost always covers gaps in the
documentation, such as "oh yeah, you have to also call that function,
first". Something about documentation makes those gaps inevitable,
Something about developing without a process may make those gaps
inevitable, but in well run shops, they don't get through code
review. And just looking at code will never really tell you
whether the function f() has to be called before function g(),
or is only called before it in this particular example. Whether
the f() must be called first must, in fact, be known before the
author writes g(), and as I said above, it's not "known" unless
it's written down. After that, the code review ensures that if
there is no requirement that f() be called first, there are unit
tests that don't call it first. But until the requirement is
stated, the author of g() can't write any code, implementation
or unit test, since he doesn't know what to write.
and if
you can't beat unit tests, join them!
Except that unit tests are a lot more wordy than good
documentation, and if you don't have the documentation to begin
with, then you have no way of verifying that the unit tests are
complete.
Developers should lean on their unit tests - even leaving
redundant code in them - to push up their self-documention.
Unit tests should be "self-documenting" in the sense that you
don't need any additional documentation to understand them. But
the user doesn't normally have access to them, nor should he.
--
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