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 _______________________________________________ sssd-devel mailing list sssd-devel@lists.fedorahosted.org https://lists.fedorahosted.org/admin/lists/sssd-devel@lists.fedorahosted.org
