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.
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.
> 2. Next level, documentation tax: if you touch anything, document
it. Modified
> a module header? Add a short module description. Added or removed a field
> in a structure? Add structure and field descriptions. Changed a function?
> Document it.
better: If a developer works on a module that is confusing to
understand, document the code flow.
Partially agree,
non-obvious part should be either documented in code or refactored.
LS