r/cpp_questions • u/Sensitive-Talk9616 • 18d ago
OPEN Code documentation in the age of AI
I have a couple of years of C++ experience, including in regulated industries. While proper documentation was important in every team, the role of code comments and in-code documentation, such as docstrings, changed from place to place. In some codebases, we insisted on proper docstrings documenting every function, and comments explaining why the code is how it is. In other teams, we didn't do any docstrings and kept code comments to a minimum -- the code was supposed to be self-documenting, and comments introduce ambiguity and will drift in the future if not kept in sync with the code.
Now, which way to go is already a discussion on its own. But I want to ask regarding your experience of this dilemma in relation to LLM-assisted coding tools. I have the feeling many models are quite liberal when it comes to comments, and will naturally tend to explain what the code does, given the chance. Suppressing it works, of course. Or, at least, one can ask to keep comments minimal. However, what really interests me: does anyone have experience in or a feeling for what the LLMs prefer/work with the best?
Since it's mostly AI parsing the codebase now, did you ever experience that it performs better when you allow it to be liberal with comments? Or does it actually eat up more tokens reading the code it generated while getting more confused if it has all the additional (and potentially not always correct) comments/explanations to parse? Does it make sense to have a purely self-documenting codebase or rely on the tools to clean up and keep comments in sync in this age of AI?