As an engineer, I tend to error on the side of “this should be documented”. However, I think that with the recent push of being agile and lean, the word “documentation” has a bad connotation that comes with it. I never realized that people might have a different definition of the word “document” than I had.
Here recently, I’ve been working on training a group of developers that work with one of our clients. I started off showing them all of the product’s documentation…SDD, PRD, SRD, UIRD, and other acronyms that mean a lot to some people, and very little to others. I made a point to show them the documentation to begin with, before diving into the software itself. (This was mainly done to show them what documents to expect changes from the client in.)
Sometime later during the 4 weeks of training, we began looking at an engineering tool that we created internally. This tool had very VERY few in-code comments. This tool was not intended to be maintained, nor was it expected to be seen by others. It looked pretty bad, and was difficult to explain what some of the longer functions did, without combing over each line of code.
The day after we trained on this tool, I mentioned that they might want to begin documenting the tool if they found themselves using it more than the 1 week we used it during training. Then a LOADED question was asked….”what format should we document this tool in, and should the document be in the PLM (Product Lifecycle Management)?”
Well, that’s when I realized that my definition of “document the code” and their definition were not the same.
Summarized into my own words…
Software Documentation: Low/High level DETAILED documentation, often referred to as a manual. I typically think of this as a document that lives in some sort of configuration management tool.
Annotation: explanatory comments added to your work after you’ve written it. I typically think of this as in-code documentation.
So, back to the question…to document, or not to document?
Since we have been changing into this much more agile and lean group, perhaps we should change our lingo as well? Moving forward, I believe I will use the term “annotate”.
There are other places where such lingo is changing. I am challenging myself to be more mindful of these changes; and more importantly, to implement them when speaking with others.
Some general suggestions I’ve picked up over the years when dealing with annotations:
1. Annotations are most useful when they are correct, concise, and clear. Make sure someone else will understand your comment (assuming they have at least some domain knowledge).
2. Annotations are most useful when they are kept up to date (if you modify your code, make sure to review annotations for anything that may need to be updated). (This is really an extension of #1)
3. If you are going to take the effort to annotate, please make an effort to ensure that you have spelled things correctly and used proper grammar.
4. Make sure that the comment adds value, otherwise it is just adding clutter (don’t add a comment that just says the exact same thing as the code you are commenting).
5. Annotations can often inform you of places where it may make sense to separate code into a separate function (for example, if you wind up annotating a loop, maybe the interior of the loop would make sense to separate out into a separate function).
Wow, thanks Kyle. A couple of those I hadn’t actively thought about when dealing with annotations. Your bullets 4 and 5 are something that I personally should improve on. Thanks again!