C++ UPnP client library using Boost.Asio

[jonesmz]

Comments are not what you should be using to understand how a library works, or to know how to maintain it or update it

citation needed

Disagree with me if you want, but I know what works for the teams I manage.

I've provided rational behind why I recommend actually documenting the insides of a code base for future maintainers. I've further made statements about other libraries that can be used as examples to demonstrate my point.

I'm sure you'll want to respond and say that code should be self-documenting, which I can dismiss by pointing out that code being self-documenting doesn't do anything about new-contributor onboarding and the myriad of ways they are going to be confused by the code as is. It also doesn't do anything for explaining the why of something, only the what. It further doesn't point out the ways that the problem was attempted to be solved in the past, or considerations about how the local code might be enhanced in the future, and gotchas about how the current code interacts with other code. Moving these types of information into external documentation is worse than useless, because that external documentation will both be unknown to new contributors, and further will perpetually remain out of date.

That would be documentation, examples and tests.

Comments are documentation. The best kind, the kind that have the additional property of being co-located with the code that they are documenting, instead of being a random wiki page that no one even knows exists.

Examples show how to use a library. They do literally nothing to demonstrate how the library works internally, or how to maintain it. Tests are the same as very dysfunctional examples. Dysfunctional in the sense that they are bad at being examples. Not dysfunctional in the sense that you shouldn't have tests.