How Much Should You Comment Your Code?
How much should you comment your code? As with many things, I’m not convinced there is a “right” answer but it is something you need to consider for your situation
The extremes
Initially when we start coding we are often told to write lots of comments to explain what the code does. Bad programmers don’t comment we are told In fact recently when a non programmer was trying to work out if my code was good the first question asked was whether it is commented (the second was whether I have used OO)
Recently, in the generation z (or whatever we are in now) comments are fought against, with some advocating you shouldn’t comment since the comments are often out of date with the code and become misleading. The idea is if you write good code (well named variables, functions, clean) then they can tell you more than comments anyway.
So Who’s Right?
As usual it isn’t black and white.
The idea of not having comments because they become out of date is rubbish. You are a professional, it is your job to make sure your code is readable and correct so if your comments are regularly out of date you have failed, do better next time.
The reality is thought I think this standpoint comes from a reaction to overly commented code. The comments should not just describe the code in gritty detail, that is what the code is for! So let’s not throw out the baby with the bathwater.
So what should you do?
As with anything step back and try to understand why you are commenting. What benefit are you looking for? Why is it hard without it? This should lead you to an answer.
For me comments should enhance the code and say something that the code doesn’t on its own. Off the top of my head these would be things like:
- The overall intention of a block of code that doesn’t make sense as a subVI but works to a single goal. (This one is a little dubious, often a subVI might be the better choice)
- Design decisions for why you have structured the code the way you have.
- Translating code terms into real world terms. For example using sub diagram labels that says ‘this step is complete’ rather than the standard “true” or “false” of the case statement.
- Units and derivations of constants and numbers, why are we dividing time by 3600? (Hint: seconds in an hour)
An interesting thing with these is that because they don’t just describe the code, most of them shouldn’t go stale over time since the outcomes of the code will often be the same. If all you do is say what the code is doing, every code change then means a comment change, and you can see how these can get missed.
Have I missed an obvious case? Let me know in the comments.
Steve Watts
February 17, 2016I take the view that a comment describing the action will generally only be trustworthy at the point in time that it is written. This also applies to a lot of documentation. If you need to describe what a piece of source code is doing I would think about refactoring until it can explain itself.
That said we label constants, structures and shift registers, these actually help the process of design as well as helping understand the code.
We also extensively use language based programming (enums, strings, polymorphic selectors) to this end.
I guess the key point is whether you are improving the understanding of the block diagram and the design decisions you have made.
I also think people are different, some people will prefer working from descriptive texts, others prefer uncluttered code.
My position is that you can only trust the source-code, so make it readable.
James McNally
February 17, 2016Yes I probably should have mentioned refactoring too.
I think comments are the icing on the cake for readability. If the code is difficult to read on it’s own you should think about refactoring in subVIs etc. first as the comments need a solid base to work from.
I agree (and we have discussed in the past) about documentation! At the end of the day the code is the only true representation of what is actually happening. What has triggered this train of thought for me though is that code alone can’t show everything I want and I’m trying to understand the right balance between code, comments and documentation. I think you need to get less dependent as you go through this, code is most trustworthy, followed by comments (as they are closer to the code and more likely to be updated), followed by documents (which are often created and not revisited)
Jeffrey Habets
February 18, 2016Great thoughts!
I think the comments should indeed supplement the code in a way it enables other programmers (and yourself 6 months from now) to see what the code does at a single glance (e.g. without having to analyze the code thoroughly) or alert them to pitfalls, design decisions and such. No more than that. Your examples just about sum that up.
As for documentation, the only documentation I generally will make (unless customers request otherwise) are diagrams: system diagrams, UML class/state/sequence diagrams.
And then there’s the ‘VI Description’… Is this source-code comment or do we call it documentation? The fact is that it is IMHO still underused. I’m amazed to still see tool-kits that are publicly released that have empty descriptions in their API VIs. I know that a lot of sub-VIs’ functionalities are self explanatory by looking at the icon and connector-pane, but as soon as I find myself having to open the sub-VI to figure out what to wire to the inputs I think that is a major fail of the programmer of that particular sub-VI.
So the VI Description is for me also a very important aspect of source-code documentation, especially for the public API’s of modules/classes. They are however probably also the most prone to getting outdated. Does this justify not using them? No, absolutely not. I’d take an outdated description anytime over no description at all and having to dig into the VI to figure out what to wire to it. 🙂
James McNally
February 19, 2016Hi Jeffrey,
I agree regarding external documentation. I do find myself creating various UML diagrams (I plan to write more on the topic but I think they are good so you can look at the problem from a different angle)
VI description is certainly one that I can be guilty of missing! As you describe the power of this is from the level above so were I am always sure to complete it is when I have something that isn’t obvious how to be called from the API. It’s unusual for example if there are pre-conditions or if the inputs need more detail.
I agree on toolkit APIs as well, I would always expect to have this completed there.