9.4 Commenting Code

Commenting is a practice that should not be overlooked by new users of Python. As easy as it is to write a few lines of script, it takes only a few more seconds to quickly document what those lines do. This comes in handy in a multitude of situations such as:

  • Sharing code and projects with other programmers

  • Maintaining code in older projects

  • Changing the functionality inside of a re-usable component

It may seem frivolous when scripts are brief, but it is a habit that should be solidified from day 1. Look at the example code below:

  1. a = 10
  2. b = op('value')[0]
  4. op('op12').par.rx = b
  6. c = str(op('numbers')[0])
  7. d = 'testing'
  8. e = 'something'
  10. op('lines').par.text = d + e + c

This script is hard to read for a number of reasons. The main reason is that its actions weren’t obvious when quickly skimmed. One quick way to increase the readability of this script is to comment it. Let’s take the above script and add some basic comments to it:

  1. #Set initial variable
  2. #get the value from slider input
  3. a = 10
  4. b = op('value')[0]
  6. #assign the slider value to video input rotation
  7. op('op12').par.rx = b
  9. #take numeric input from computer keypad
  10. c = str(op('numbers')[0])
  11. d = 'You'
  12. e = 'pressed'
  14. #create a sentence from variables above
  15. #add it to a Text TOP to display
  16. op('lines').par.text = d + e + c

Without taking the time to create meaningful variable and Operator names, the above script is still much easier to read through. Even out of context, the function of the script is apparent.

This kind of simple addition can make collaborating with other developers much easier and more enjoyable.