Writing Comments First To Increase Productivity

Tim Eriksen — Tue, 21 Jan 2020 09:21:03 +0000

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):

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

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

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

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!

DEV Community: Tim Eriksen

Writing Comments First To Increase Productivity

Defining an example task

Getting started

Writing the code