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