DEV Community

Cover image for Writing Comments First To Increase Productivity
Tim Eriksen
Tim Eriksen

Posted on

Writing Comments First To Increase Productivity

The code in this article is written in Python but this method applies to what ever language you prefer.

We can all probably agree that commenting your code is generally a good practice. If you have followed a coding tutorial or attended a programming class, then you have likely heard some variation of the line «comment your code» before, and for good reason. Making sense of a project that you haven’t touched in a few months, can be pretty time consuming without proper comments.

But did you know that comments can be useful for more than just inline documentation? Here is a little tip that can help you actually remember to write comments, and increase your productivity at the same time! If you are familiar with writing "TO DO" comments or pseudo code, then this method should feel familiar.

Defining an example task

Let's say you are working on a project and your next task is to add a simple function that will find and read a query stored in a file. The function is required to:

  • Accept a query name/file name as an argument
  • Read the query from the file
  • Return the query

Getting started

Alright, so you know what the task is. You may even have a rough idea of how you would like to approach the task. After taking some time to research any parts of the task you may be unfamiliar with, it is time to write some code!

def get_query(query_name):
Enter fullscreen mode Exit fullscreen mode

Aaand that’s enough code for now. How come? Well, that’s what this is all about: you write the comments before you write the code. Why would you do that? Because it gives you a chance to really think through how you want to solve the problem before you have to start thinking about syntax, error handling, naming variables, remembering what that one method was called, and so on. Think of it like drawing a quick sketch before painting the final picture.

So how do you get started with this «comments first» approach? It is rather simple. You figure out the major actions that the function will need to perform, and then you write those actions down as comments in your function. Sort of like a bulleted list.

def get_query(query_name):
    # Add file ending to query name if not included
    # Get path to the file
    # Open file, read contents and close file
    # Handle file error
    # Return the query
Enter fullscreen mode Exit fullscreen mode

Great! Even tough this function dosen't really do anything yet, it is already easy to grasp what the function will do.

Writing the code

Here comes another benefit of this method: you now have sort of a "to do list" of the functionality you have to write. To start writing your code you simply add a new line under det first comment and write code to match the comment. Like this:

def get_query(query_name):
    # Add file ending to query name if not included
    if query_name[-8:] != '.graphql':
        query_name += '.graphql'

    # Get path to the file
    # Open file, read contents and close file
    # Handle file error
    # Return the query
Enter fullscreen mode Exit fullscreen mode

Then you just keep on going, comment by comment. Does new things come to mind as you implement the function? Write them down as comments! If you get distracted by coworkers, leave for lunch, or your energy is low and it is hard to keep focus, the outline for your solution is already written down. Picking up where you left off is no problem.

def get_query(query_name):
    # Add file ending to query name if not included
    if query_name[-8:] != '.graphql':
        query_name += '.graphql'

    # Get path to the file
    query_path = path.join(path.dirname(__file__), f'queries/{query_name}')

    # Open file, read contents and close file
    try:
        query_file = open(query_path, 'r')
        query = query_file.read()
        query_file.close()

    # Handle file error
    except FileNotFoundError:
        logging.error(f'Query "{query_name}" not found')
        query = None
        pass

    # Return the query
    return query
Enter fullscreen mode Exit fullscreen mode

There we go. The task is finished. The code is commented so that it requires less effort to understand. Developers reading this code in the future (including yourself) will be thankful!

The "comments first" method is even more useful when writing larger and more complex pieces of code than what we did in this example. It can also be a good early step in planning the implementation of a project.

I hope you find this method useful and that you try it out at some point!

Top comments (2)

Collapse
 
mateusz__be profile image
Mateusz Bełczowski

Hey, I really like this approach and I'm also using it pretty often. I think that it's really powerful if you combine it with unit tests :)

PS. pathlib is pretty awesome for working with paths :)

Collapse
 
timeriksen profile image
Tim Eriksen • Edited

Hey, thanks for reading! Glad there are more people out there using this approach :) I'll be sure to check out pathlib, thanks for pointing it out!