On 07/20/2016 06:42 PM, Lukas Slebodnik wrote:
On (20/07/16 17:41), Nikolai Kondrashov wrote:
> Depends on how much outdated it is. Even 25% outdated documentation is much
> better than no documentation. Besides, code gets outdated too. Some code gets
> updated and some of its uses don't, and we live with that, we don't have
tests
> for *everything*. It doesn't mean we shouldn't write or update code. The
fact
> that documentation gets outdated sometimes, doesn't mean we shouldn't write
> it, or try to keep it updated.
>
outdated documentation == confusing documentation.
confusing documentation => bad thing for newcomers.
As long as most of it is right, it will still deliver a lot of useful
information. Yes, somebody will get confused about some things sometimes, but
they will still get the picture, and we will be here to accept the complaints
and fix it.
> I argue that the effort of writing documentation and keeping it
updated is
> worthy. It makes life easier for existing and new developers alike, including
> external contributors. Reading more often than writing, etc.
It still does not make sense to me why is documentation better than unit test.
Because it's natural language, it's designed for humans, and it says directly
what the code does and for what. You don't have to derive the knowledge by
reading some more code. It's there, just read basic English.
People don't communicate in unit tests written in C, because they're hard to
understand. Even for developers who do it all day, every day.
>> Therefore it is much better to write unit tests for
functions.
>> a) they cannot be outdated. (they have to pass)
>> b) you can see a usage of functions.
>> c) if it is a hard to write unit test than it means that functions is
>> complicated or do a lot of things and should be refactored. => refactored
code
>> will be easier to read, to understand and to test.
>
> Unit tests are great and can help understanding, but they're not a substitute
> for documentation. Documentation is written in natural, human language, is
> easier to digest, and tells *directly* what that code/structure is for.
>
Examples are much better than documentation of arguments.
Unit tests are examples of how to use functions. The unit test should contain
ordinary use case + corner cases with error codes.
Examples are great, without doubt, but they're not the same as documentation.
Let's take a simple (made up) piece of information. To communicate the
possible return codes in documentation, you need just a few sentences of
clear, direct human language:
EOK - user added successfully,
ENOMEM - memory allocation failed,
EAGAIN - operation needs to continue asynchronously from the main loop,
EINVAL - user name was invalid,
EEXIST - a user with the same name already existed, user not added.
How much test code will you need to write and read to explain and understand
all that?
The biggest benefit is that you cannot have outdated unit tests.
That is sure a very nice feature of tests, which helps make them good
examples. BTW, people writing programming books often setup test systems to
verify their example code, so it works both ways.
So, unit tests are good examples and help improve code, but they don't help
understanding as much as natural-language documentation.
We could write examples to comments as well. IMHO it does not worth
the effort.
It make sense for public libraries with stable API.
I don't think we should write example code in comments, if only really rarely.
And I think we can benefit greatly from code documentation, in *addition* to
unit tests.
Nick