There is nothing like that for comments except your eyeballs, and everyone makes mistakes. Remember, the compiler/linter can tell when you have a syntax/semantic/logic error.
#Doxygen comment after member generator#
Since you’re exposing the implementation to strangers, you might want to comment more prolifically, but you need to be very diligent maintaining them and keeping them up to date. Doxygen is a tool or command line-based documentation generator that helps in writing reference documentation for software. Comment rot is real and creates more of a time waste than just reading the code. Generally, try to make your code self documenting. Inline Doxygen comments are discouraged except in the documentation of data members of structures. It’s a waste of time to keep design docs up to date, but they can be useful in hindsight when you want to understand why something is the way it is. Document the design there and make sure to clearly date it. Senior devs generally don’t comment.įor large complex designs, you should not have this documented in code at all. Junior devs tend to comment way too much. Sometimes they’re necessary but usually not. For complex algorithms or code that cant be made self documenting, out a comment where it needs to be (eg in the cpp for implementation detail, in the header for some other weirdness, like order of operation callouts).Ĭomments are a code smell. good names, good abstractions, restrictive inputs, and unit tests which can be used as examples). You can even just put it in the headers and they will find it.įor internal people, documentation should be a last resort. As long as your documentation has that, the format doesn’t matter. The end user cares about: what the inputs are, what the outputs are, conditions/expectations/edge cases/threading concerns of this function, and maybe an example. I will assume you’re working on a closed source project.įor external users whom you are exposing an API surface, doxygen is decent, but not required. First, depends on what you’re documenting.
0 kommentar(er)
