[DawsonBruce]

I’ve recently joined a team where the vast majority of the code used across different projects has been written by a lone developer. The code quality is quite good, however, nothing is documented thoroughly and it’s mostly understood by a single person.

We’ve started to code review all new code being merged to the the codebase, we’ve been pair programming occasionally, and I’ve also been writing documentation about how to use the code as I get a handle on it. It’s been helpful so far.

Please document your code. Please provide examples.

[protonbob]

What does well documented code look like for you? For me if I look at a new (webapp) repo I start from the controller level and look at the services and models. Would a good swagger page count as good documentation? My worry with documentation is that it can lie but the code doesn't.

[opportune]

I agree with this perspective. Documentation outside of code is almost never worth it (you cannot capture all the nuances or current bleeding edge - only code can) and usually just an excuse for someone to throw up their hands and not understand something.

There is value in guides, and good comments. For a library all the external functionality should be described (including prescripticely). For a big ol code base? Read the code and follow references!

[DawsonBruce]

The good documentation I’m envisioning refers to standardized comments throughout the codebase (we’re working with cpp, so doxygen in this case), with code examples within the header showing how the code should be used.

I’ve found there’s so many custom classes through my discovery if this codebase that it’s not quite clear how to use the classes or where to start, so having code examples along with comments describing their usage is pretty useful.

It’s also nice to utilize version control for the comments, which makes them easy to contribute to, as well as hopefully inspires others to contribute their own thorough comments when designing and contributing new classes to the codebase.

Documentation regarding process, coding guidelines, and the likes are better suited for a platform like confluence or some equivalent. We do that as well.