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.