Re: Doxygen comments in C++ source

> so i guess my proposal would be, write Doxygen comments if you really
feel like it, but with the understanding that it's temporary. either way,
code quality comes first.

"code quality comes first" is only meaningful once we have standards on
"code quality". Right now the guidelines are very slim and not enough to
really amount to quality code, IMO. If you really believe this, then we
ought to spend time working on those.

To go back to the original point: I don't think that anything in this
codebase is going to improve unless we do it incrementally. The best way to
accomplish that is by tying those incremental improvements to new changes
and additions. That way, we're guaranteed that new contributions can only
decrease the technical debt of the project, at least for some obvious but
concrete metrics of debt. Is that a controversial statement? From the
conversation so far in this thread, my understanding is that people would
like to have those incremental improvements be actual refactors and
cleanups rather than/in addition to documentation. I'm much happier with
that, but it requires significantly more work and discussion, which is why
I didn't suggest it in the opening.

-Brian

On Thu, Feb 8, 2018 at 12:36 PM, <nathan-PB1wun9k+p9Wk0Htik3J/[email protected]> wrote:

> On 2018-02-07 11:02, [email protected] wrote:
>
>> Hey all,
>>
>> In my last few PRs that modified C++ source, I added Doxygen comments
>> for the functions I added/modified. Since the codebase is somewhat
>> lacking in documentation, I was wondering if we could establish some
>> organizational rules about this. Specifically:
>>
>> - Any new C++ code must have Doxygen comments
>> - Any changes to existing C++ code must add Doxygen comments if
>> they're not present
>>
>> - This applies to all documentable elements - functions, data (such as
>> class members and globals), enums, classes, and files when appropriate
>>
>> - In header (hpp) files, document the element according to its usage
>> (preconditions, parameters, return value)
>>
>> - In implementation (cpp) files, document implementation details if
>> necessary
>>
>> - If the element only exists in an implementation file, document both
>>
>> - If the element is trivial and can be determined from name alone, it
>> doesn't necessarily need to be documented.
>>
>> Ideally, over time, this will lead to the most commonly touched parts
>> of the codebase becoming well-documented, making them easier to
>> understand and modify in the future.
>>
>
> hi brian,
>
> my view is this: good code with prose documentation > good code with
> generated documentation > good code with no documentation > bad code with
> generated documentation > bad code with no documentation. in an ideal
> world, all our C++ is pristine and documented with comprehensive articles.
> in practice we can settle for lesser alternatives in the interest of saving
> work.
>
> so i guess my proposal would be, write Doxygen comments if you really feel
> like it, but with the understanding that it's temporary. either way, code
> quality comes first.
>
> you, josh, and i have agreed on one thing though: documentation of
> sclang/scsynth source should be done in an established documentation
> system, not SCDoc. i would like to see all scsynth development tooling to
> be self-contained with no dependencies on sclang. (there are vague plans to
> phase out SCDoc anyway, but that's a discussion for another thread) we
> could use Doxygen for this, and i'm also partial to Sphinx if we don't mind
> a Python dependency.
>
>
> nathan
>
> _______________________________________________
> sc-dev mailing list
>
> info (subscription, etc.): http://www.birmingham.ac.uk/fa
> cilities/ea-studios/research/supercollider/mailinglist.aspx
> archive: http://www.listarc.bham.ac.uk/marchives/sc-dev/
> search: http://www.listarc.bham.ac.uk/lists/sc-dev/search/
>