Jump to content

When to comment your code


Recommended Posts

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.

  • Like 1
Link to comment

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.

Link to comment

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.

Link to comment

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".

Link to comment

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.

Link to comment

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>".

Link to comment
(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  :lol:

Edited by for(imstuck)
Link to comment

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.

Link to comment
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. :)

  • Like 1
Link to comment
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.

  • Like 1
Link to comment
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.

Link to comment
  • 1 month later...

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.

Link to comment

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

×
×
  • Create New...

Important Information

By using this site, you agree to our Terms of Use.