Should we use any formalized formatting system for comments like Doxygen?

[rbrunner7]

@DangerousFreedom1984 wrote in issue #23:

---

4) I really want to keep Koe's high standards in writing c++ files and avoid code and design smell. So should we also use Doxygen or something like that to better document the files?

---

For reference: https://doxygen.nl/

[rbrunner7]

@UkoeHB answered:

---

It might be worth a try, but maintaining that would become an ongoing task. I also don't know if the cleaned-up header comment style I'm using will work with Doxygen (iirc they use @param and so on, which is ugly):

/**
* brief: func_name - comment
* type: type - comment   (for templates)
* param: param - comment
* inoutparam: param_inout - comment
* outparam: param_out - comment
* return: comment
*/
template <typename type>
return_type func_name(param_type param, inoutparam_type &param_inout, outparam &param_out);

[rbrunner7]

@DangerousFreedom1984 's answer to that:

---

Yeah, on top of the name conventions/organization that you are using, I will try to at least write a few words for each function. It looks better than nothing to me.

[rbrunner7]

In my experience this "commenting every parameter" style soon degenerates into trivial comments that are pretty much worthless to everybody with even a little understanding of the codebase. Plus, the better the names of the parameters, the less need there is for additional comments, and those names better be good.

There is more: Those comments tend to rot, like koe also hinted at, and may become a net negative if you can't rely on them. Finally they make the header and code files longer and thus less readable.

[rbrunner7]

I recently had the task to give some advice at the company I work and came up with the following general approach:

When you write comments try to put yourself into the shoes of the reader of your code, using as much "empathy" as you can muster, and ask yourself: Which important facts about the code in question would be the hardest to understand for that reader from looking at the code? What would took them the longest time to understand from merely looking at the code without any support from additional info in the form of comments?

Then comment at least those facts.

There are some candidates for such things that I encounted repeatedly in my own programming:

• Sometimes, despite my best intentions to come up with a good structure for my program, and apply good layering and good modularization, several parts of the code have to work together in non-obvious ways. The parts that "belong together" in this way are hard to find without some pointers in the form of comments, and there is the danger that people unintentionally break things by uncoordinated changes.

• Sometimes a piece of code looks wrong at first sight, but is correct nevertheless, and it might be hard to understand why. I take great care to comment each code piece that "surprises" readers in this way, to make sure nobody "corrects" it later out of limited understanding.

• Sometimes I don't implement some feature, to keep things simple, and because I am sure that the feature won't be needed right away, and maybe later will be needed in a different form that I am not yet able to correctly predict. (I call this the Nothing in advance principle). If I do that, I carefully document what I did not implement, and why not, so nobody later implements what I so carefully and thoughtfully left out, just because it looks missing or in need of improvement.

• Sometimes my code looks sub-optimal, as if I did not choose the best way to implement a piece, but in fact I did think through alternatives and saw non-trivial disadvantages in those ways that may look more attractive at first glance. Sometimes I try to comment those discarded alternatives and their non-obvious problems, again to avoid that somebody falls into the trap to rework my code and ends up with something worse.

[UkoeHB]

One thing I'd really appreciate when everyone reviews the seraphis code is to point out confusing points that could benefit from code comments (and also existing code comments that are confusing).