Respect your time

I think many developers have experienced opening up a project directory they haven’t touched in a few years and spending a couple of  hours piecing together the logic therein. A simple example of this is that sometimes it takes me a second or two to recognize a concise one liner for something like reversing a string, even if I wrote it. But placing comments as in the following examples takes all the hard work out of remembering.

Check this out:

# This first one, reverses a string, but unless you're well versed in python fu
# you wouldn't know that.  Since this is so short, we can in line a comment and
# not even upset pep.  Now instead of reading the python docs about extended slice
# notation, someone trying to figure out what the heck this script does can
# immediately understand.
 
'hello world'[::-1]  # reverse string
 
# This next one is a little more readable, but according to someone on stackoverflow
# executes slower. Which makes sense because of the implicit object instantiation.
# The single quotes at the beginning of the line actually create a new string object
# in memory by storing charge on a combination of a transistor and capacitor.
# Computers are awesome. The same principle applies here; easy, in line, to the point.
 
''.join(reversed(s))  # reverse string
 
# This one is appropriate for a one liner, because of the short block structure.
# It's essentially the same as the first example but more explicit about what
# values are going where.  That takes up a few more lines and the word, 'reverse'
# being in there is somewhat helpful, but putting the comment in makes it ultra
# readable. 
 
# reverse a string
start = stop = None
step = -1
reverse_slice = slice(start, stop, step)
'foo'[reverse_slice]

I personally am in favor of easily readable code over code that’s compressed into as few bytes as possible by an overzealous developer.  The point here is: a simple inline or one line comment goes a long long way when it comes to picking up your old work. So do future you a favor and place some appropriate comments.

Respect the time of others

There’s also the perspective of other developers to consider.  I think one of the greatest things about easily readable and understandable code is that it makes it easier for others to review, thereby making it more likely that the person who wrote it will receive valuable feedback and improve as a result.  Another aspect of this secondary perspective is with respect to collaboration.  No one likes being asked a bunch of questions when they’re trying to get stuff done, and if you’re collaborating on a complex project and not putting in appropriate comments, you’re only increasing the chances of interruptions in the interest of the efficiency of others who need to understand what you’ve written; ironically and obviously, this reduces your efficiency.

Finally there’s the benefit of eliminating the “why” question.  I’ve often been reviewing code or refreshing on something I created in the past and found myself wondering, “why was this done this way?”  When it’s appropriate, putting in a little block comment about why a decision was made can be really helpful.  These allow you get to know your fellow developers, learn from their thought processes, and relieves the conversational burden of explaining yourself or revisiting a topic.  The reasoning is immortalized right there in the code.

Overall…

The bottom line is efficiency.  Comments help you and your team be more efficient in collaborating on code and maintaining projects.  More efficiency equals more free time; time is the ultimate currency, you can’t make any more of it.

References:

https://stackoverflow.com/questions/931092/reverse-a-string-in-python#931095