![]() ![]() The more comments that are in your code, the higher chance something slipped by and you have a misleading/incorrect comment. 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. 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. Comment rot is real and creates more of a time waste than just reading the code. Generally, try to make your code self documenting. 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. There are several types of entities to be documented: types, variables (both global and members), classes, class methods, functions, and components. good names, good abstractions, restrictive inputs, and unit tests which can be used as examples). Doxygen is a tool or command line-based documentation generator that helps in writing reference documentation for software. 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 Comments
Leave a Reply. |