When to comment your code

[Tim_S]

I ran across an article on when to comment you code. Thought I'd pass it along as an interesting read.

http://ardalis.com/when-to-comment-your-code

[Darin]

I will once again state the analogy that many of you have heard me make elsewhere:

 

Text comments in LV are like writing the letters next to the notes on a sheet of music.  You should be able to "hear" the tune just by reading the music.

 

Comments are for:

References.

Copyright

Notes to self (doing this because of LV bug xx, finish this)

Why the code is there (covers requirement xxx)

 

Comments are not for:

This is what the code is doing.

 

Grey area:

Equations, G has a tough time representing equations.

[Cat]

Maybe the concept of self-documenting code is the Holy Grail we should all be striving to attain. However, we need to be careful about declaring our own code has reached this state.

 

Code is only self-documenting when someone with a basic knowledge of the language/environment and the goal of the code can, having never seen it before, read it, and understand how it does what it's supposed to do. In other words, it's something the developer should not be the judge of for his/her own code (of course we all understand our own code! If we don't, no amount of commenting will help).  I have been stuck on several occassions with having to wade thru someone else's "self-documenting" code and it has been anything but.

[GregFreeman]

I disagree with Darin a little...I think there are valid times when you should comment on what the code is doing. Sometimes what may be self documenting to you is not as self documenting to others. I run into this commonly with bit manipulations and bitwise functions, and lately even more so with FPGA. Often times if someone just left a comment "this checks if bit 4 changed" I would understand quickly vs. trying to read the ands and ors and scale by power of 2's that my mind doesn't yet process as easily. Maybe this is my own shortcoming, but I still think it's worth noting. The problem is at what point do you determine whether something is self documenting in general and the majority of programmers would agree that it is, or whether it's self documenting just for yourself (code reviews, anyone?). I find myself looking at my own code and thinking "that makes sense" but forgetting that it took me 3 hours to get it to work. Anyways, this is just one example and I think touches on the same thing Cat is saying above.

 

One thing I am always sure to document is the random "increment" or "decrement" function. C'mon, we've all seen this, the code works, yet we wonder wth is that there for!

Edited May 9, 2013 by for(imstuck)

[Darin]

Bit twiddling falls into the grey area since I consider that a simple formula that G has a hard time representing.  I am talking more about the play by play comments you see (Add two values together and multiply the result by x).  Close the reference.

 

You should need relatively few comments if you:

Provide useful names, descriptions and icons for subVIs which should be doing one thing most of the time.

Provide visible labels for constants, and display the most useful radix (b1000 is often better than 16 for bit operations)

Maintain low to medium density of nodes with a neat BD

 

I'll rephrase by saying, you should be commenting on the algorithm, not on the implementation.  Comments should ADD information, not simply rehash the BD.  Naming a song Waltz helps you when it comes to reading the sheet music.

 

For example, I am ok with saying "check if bit 4 has changed".  I can look at the implementation and decide on its correctness.  I think saying "take XOR of old and new values, then AND with 1<<4" is superfluous.

[ShaunR]

I'm sort of on Darins side here. (I would add examples to the list of "comments are for"). Of course. I think most are all talking about comments in English. I wonder how useful Chinese comments would be to most non-Chinese LV programmers or, conversely English comments for Chinese? Comment language is not a problem for a graphical environment

 

Generally I look at a piece of code and add a quick comment if it is likely I will not understand it "easily" myself in three months time (I tend to have a FIFO memory with limited heap) . For the rest, (taking account of Darins list) if you can't understand it from the other documentation (like the VI description or the design spec), then you shouldn't be hacking away at my code. Detailed design specs are for communicating function, not the block diagram.

 

</RANT>

And while we are on the subject. I hate people that cover wires with labels! I'm perfectly able to trace wires through the system EXCEPT if you cover them up with labels.Above, below, above to the left or right; fine. But not on top!.

</END RANT>

 

There is no such thing as "self documenting code", There is only "well designed code with documentation" or "experience.and expertise".

[Darin]

I should add one of my other "rules" here which I call the "What the F*&*( Rule".  You are often faced with a situation where the easy to read code is *slightly* slower than a crazy, ultra-complex, unreadable alternative.  Inevitably you are going to open it up a few months later and say WTF?!  If all of the complexity saved you a microsecond, that code will have to run millions of times to make up the time it took you to say it.  Not to mention the extra time spend coding it up. 

 

And let's say it passes the WTF rule and is worth the complexity, in order to save it from your future self, or your replacement, you may want to mention why you chose the complex solution.  Otherwise, someone will be very proud that they replaced a bunch of crazy code with a couple of functions, or think it looks better when that constant is moved outside the loop.  Only later will they ask why it is so much slower.

[todd]

It's a judgement call about what basic knowledge is, or what future self knows.

(I knew a manager who didn't let people use structs in their c code because a "person off the street might not understand structs".)

 

One category I'd add is the occasional note about "if I had to write this from scratch, I'd do it <this way>".

[GregFreeman]

(I knew a manager who didn't let people use structs in their c code because a "person off the street might not understand structs".)

 

My counter argument to this would be: Then don't hire that person (assuming they wouldn't be willing to learn to understand them).

 

 

 

I tend to have a FIFO memory with limited heap

 

Stop using lossy enqueue element and this problem will go away 

Edited May 10, 2013 by for(imstuck)

[BigAngryHillMan]

I comment my code, not because I it is too complex to follow but because sooner or later the code my code will always end up in a production environment.

From experience I have found many times that after a very long day trying to get a production line up and running again a comment in the right place can save a lot of time when you are tired.

This is doubly so when the person working on you code is not you but some poor engineer who has to  work out the problem in your absence.

[Cat]

This is doubly so when the person working on you code is not you but some poor engineer who has to  work out the problem in your absence.

This is exactly why I'm attempting to go back over 10 years of code and add comments. I'll be retiring in the not-too-distant future and there is no one in my group who can do what I do. I keep reminding Management of this, but we have a long history of letting highly skilled technical people walk out the door without first finding someone they can train up to replace them. So I've been slowly adding comments (where appropriate) to the 2500+ vis that some bright-eyed recent college graduate who did a project once in LabVIEW, and therefore must be an expert, is going to be handed some day.  Hopefully it will help...

 

If not, they can always hire me back as a part-time contractor making 3x what I'm being paid now.

[Tim_S]

I'm sort of on Darins side here. (I would add examples to the list of "comments are for"). Of course. I think most are all talking about comments in English. I wonder how useful Chinese comments would be to most non-Chinese LV programmers or, conversely English comments for Chinese? Comment language is not a problem for a graphical environment

My company has a German office that also programs LabVIEW code. Their comments are, of course, in German, but so are the control labels. My German is limited to things such as sauerkraut and bratwurst. I could identify the ideas of what was happening, but fully understanding the code was very difficult.

[todd]

My counter argument to this would be: Then don't hire that person (assuming they wouldn't be willing to learn to understand them).

I agree. They wanted cheap, plug-n-play labor. Management were the "gurus", and staff just executed. That's why I left.

[Grey]

As possible as the comments neatly written and "smaller" than coding diagrams.it's OK for me  

[JKSH]

A bit late to the discussion, but I'd like to add: I use comments to document the assumptions made when writing a section of code. As a piece of software grows (or if code is copied into another project), some earlier assumptions may need to be revised.