On (20/07/16 17:41), Nikolai Kondrashov wrote:
Hi Lukas,
Thanks for your response!
On 07/20/2016 05:28 PM, Lukas Slebodnik wrote:
> On (20/07/16 15:17), Jakub Hrozek wrote:
> > On Wed, Jul 20, 2016 at 03:53:54PM +0300, Nikolai Kondrashov wrote:
> > > I suggest several measures which could be taken.
> > >
> > > 1. Require *every* new module/function/argument/structure/field to be
> > > documented. It must be at least a sentence for each. A module or a
bigger
> > > data structure could warrant more. Describe module/function/structure
> > > overall, and each of its declarations/arguments/return values/fields.
> >
> > I'm OK with documenting interfaces and concepts, but not OK with
documenting
> > every function. I would rather spend time on making the code more readable
> > than effectively creating two places to maintain (the code and the
> > docs). Especially for static functions, I really don't see the value.
> >
> > So I'm fine with adding documentation to headers, but I think it's
> > busywork to add doxygen headers to every function.
> >
> > I also think it's OK to document why the code does what it does, but
> > documenting private interfaces wouldn't help in my opinon, but adding
> > more comments to the code does.
> >
> BTW we already have a documentation for public fuction in libraries.
> Becasue it is stable API.
>
> Internal functions are not stable even thought they are public.
> The biggest issue with a documentation is outdated documentation.
> Outdated documetation is worse that code without documentation.
> Yes, we could check it as part of review but people are not perfect
> and we can miss that.
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.
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.
> 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.
The biggest benefit is that you cannot have outdated unit tests.
We could write examples to comments as well. IMHO it does not worth the effort.
It make sense for public libraries with stable API.
LS