I have another advice for you:
Don't over comment your code.
Examples of comments no one will ever need:
# Initialize the previous value of X tag to None
previous_x = None
If someone doesn't understand that code, no comment will ever help.
# Check if X tag value has changed
if x_tag_value != previous_x:
Pretty much as above. The variables names are clear, you don't need to over-explain.
# Update the previous X tag value
previous_x = x_tag_value
I guess you get the point by now
# Check if the new X tag value is one of the specified rates
if x_tag_value in rates:
The code is clear enough here as well.
# Calculate the new Y tag value based on the rate for the current X tag value
y_value += rates[x_tag_value] / 60 # Divide by 60 to get the rate per second
That line could warrant a comment, but I suggest explaining why you're doing something instead of what you're doing. Anyone can see from the code that it's doing a calculation, and adding a comment to tell you what variables you're using in that calculation doesn't say much. # calculate the rate of {whatever} per second is more helpful. But using a self-explaining variable name would render the whole comment useless anyway.
# Write the new Y tag value to the Y tag
system.tag.writeBlocking("[default]PredictionTabTags/O2LanceTEST", y_value)
# Read the current value of the X tag
x_tag_value = system.tag.readBlocking("[default]PredictionTabTags/ModelSuggestedO2Rate")
Yes, the function names contains tag.write* and tag.read*. The reader should be able to figure out that they write to a tag / read a tag.
# Call the function to update the Y tag
update_y(x_tag_value, y_value)
Here as well, the function is called update_y. You don't need a comment that says "call the function to update y"
# Sleep for 1 second before checking the tags again
time.sleep(1)
You probably already know by now what I would have said, so I won't.
The point is: comments should HELP the reader understand what's going on. If they don't, remove them.
Too many comments just add bloat and make code hard to read.
Over commenting is a pet peeve of mine. I tend to believe that if you need to comment everything, it should be better written in the first place as to not require comments.
I use 2 types of comments:
- the docstring that explains what a function is for and how to use it: what parameters it expects, what it returns, maybe give an example if it's not straight forward.
While I like functions that don't need too much explanation (clear name, obvious parameter names, etc), having a consistent doc string format helps create a sense of cohesion in a code base, and more importantly they allow auto-generated documentation and can be retrieved through introspection (with help())
- inline comments that explain the logic or a difficult line of code (regex for example).
You're using an equation ? Explain that.
You're using something that's not obvious ? Explain that !
Here are examples from my own code:
# NFKD: https://fr.wikipedia.org/wiki/Normalisation_Unicode#NFKD
nfkd_form = normalize('NFKD', s)
Do you know what 'NKFD' is ? Me neither. When I wrote this, I knew. Now ? Couldn't remember for the life of me.
def chunks(it, size, fval=None):
"""
'Chunkify' an iterable.
Splits 'it' into chunks of size 'size', padding with 'fval' if necessary.
params:
it (iterable): the source iterable to split into chunks
size (int): the size of the chunks
fval (): a value to use for padding if the last chunk's size is less than 'size'
return:
an iterator over a list of lists
examples:
iterable = [1, 2, 3, 4, 5, 6, 7]
size = 3
fval = 'x'
=> [[1, 2, 3], [4, 5, 6], [7, 'x', 'x']]
with size = 4:
=> [[1, 2, 3, 4], [5, 6, 7, 'x']]
"""
return zipl(*[iter(it)]*size, fillvalue=fval)
Explains what the function does, not how it does it. Who cares how it does it ! Frankly I just took the recipe from the itertools doc page.
But what it does and what to expect from it, that's what you need to know.
note: I took this example because the docstring is ridiculously long compared to the actual code, and because even if the actual code is way too hard to understand at first glance (at least for me), I still only explained how to use it, and not how it works.
Now I understand that it's my own VERY personal take on comments, but please, please, don't comment every little thing !
