Code is poetry

Today, I want to give you some insight on how to make clean Matlab code that everyone can understand.

This is a rather subjective subject but as a general guideline, I think you should think about the following:

Programming languages are meant to be a communication tool between you and the computer. So in essence, they are really languages.  As much as French and English do, each programming language has a grammar and some orthography to respect. Computers are much more demanding on the grammar. They are like a terrible French teacher that won’t let any grammar error goes through. I write this website to teach you the grammar of Matlab BUT… There is more to learn, a lot more.

Most English or French books you read respect all these grammar rules but still some are considered to be better than others.  As in French, you could write a program that is correct grammatically but is still terrible. I do believe you should consider programming as a complete language. As such, it has a form of poetry into it. Some programs are elegant while others are simply not.

As a good poem touches everyone’s heart, a good program will be easily read and can even be enjoyed by other readers. You would also be surprised but elegant programs usually run faster as if your computer also appreciates its inner beauty.

If you were to ask around, most programmers will tell you that they know when their program is elegant or not. So here is the question: How do we write elegant and beautiful programs?

To get started on this, I think you should first face your code at his core. What is it you want this code to do?

Just think as if you were starting a novel. You need to know the general story before you write. You need the scaffold of your story to be set before you write even the first word. It is the same with programming.

Sit, take a piece of paper and organize how your program will work. Ask yourself the followings:

  • Is there a simpler way to do this or that?
  • What are the different parts of your program?
  • What should be first done?
  • What should be last?

As you progress setting up the framework of your story, think of your variables as if they were characters in a story.

  • Is this character/variable important?
  • How important is it in the flow of the program?
  • Limit the number of variable to the minimum needed to make your program a nice story.

When you have all the actors in place, try to look at the bigger picture.

I clearly remember my French classes. My professors were particularly tough on repetition. The French language does not like repetition. It destroys its dynamic. Remember that programming is even worse. Repetition is a NO-NO in programming. So identify repetitive pieces of code in your story, and make them into functions and sub-functions.

As you create your functions, think of them as an entire independent story. Sub-functions can be reused in another novel so they need to be elegant in their own way as well. As such, each must have its own variables/characters properly chosen.

Once you have identified all the functions your program needs, you can consider really building the blocks.

As with books, programs are often prettier when they are made of a succession of chapters or modules. In this sense, you can look at your program as a succession of blocks that do elementary pieces of computation. In each block, make extensive use of your functions.

At this stage, you are still on your paper but everything is clear. But where to start coding?

I would suggest your start writing the core of the core, i.e. your functions. Because these are shared all along your program.

As a general rule for writing, name your variables very clearly. If a variable’s name is shorter than 3 letters, it is most certainly a bad name. Choose a name that very clearly indicates what it does like “MovieOutput” or “IterationValue”.

Comments should be used but not too much. I would suggest that you put comments (using % in Matlab) at locations where you spent a lot of time coding. These are where the code is a little bit complicated. Remember that comments can also be useless or not elegant.

Matlab has some specific needs.

  • Vectorize your code as much as possible. Just think of vectorization as a way to make your mathematical operations more elegant. Doing an operation element by element is definitely not a beautiful way to do mathematics.
  • Make use of built-in functions as much as possible. These often make your code cleaner and more efficient.

Once your functions are written, you can write your main program. If you have done a good job, this should be straightforward. Elegant code often has slightly complicated functions and very simple elementary blocks.

You should put a comment at the beginning of each block to make sure things are clearer for the future, and then you should be done.

Once your program is finished, step back, take a good look at it and breathe its essence. Nice programs are just like that… pretty.

This entry was posted in Beginners, Optimizing your code. Bookmark the permalink.

4 Responses to Code is poetry

  1. Nuwan says:

    How do you find time to spend on this blog while working as a post doc?

    • Jerome says:

      Good question. This blog has been very useful to make my Matlab knowledge rock-solid.
      You probably noticed I have been less active recently. I have been very busy with an important publication.

  2. Pingback: MatLab | New ThinKing

  3. Ben says:

    Thank you so much for the tips!

Leave a Reply

Your email address will not be published. Required fields are marked *