Attack of the code

Here’s the thing, all code is bad code. Some code is just better than others. For every person who writes a program, there’s someone else who would do it a totally different and, to them, less complicated or confusing way. However, as long as the code you write works, it shouldn’t really matter how badly it’s written, right? To me the difference between bad code and worse code is comments. The frustrating thing about taking apart someone else’s code is that there are rarely enough comments to figure out what the hell is going on.

As usual I did this to myself. I’m currently (still) writing a function for MATLAB (my favorite programming language for the type of work I do). The thing about this particular function is that it does a lot! It’s what I like to call a flexible function because you can input different types of data and depending on what you put into it, you get something different out of it. In general that something on the other side (the output) is just additive, so you get one figure, or two figures, or X figures. That’s an oversimplification, but you can think of it in that way and it will work for our discussion.

The function I’m building also does a lot of other cool things, but I can’t really say more without giving too much away. Unfortunately for the purposes of this talk, one of those “cool things” my function does is what is causing me so many headaches. Because I like pretty figures everything, or almost everything about my figures are custom placed, handmade with love so to speak. I tell my code to move the figure legend to a certain place, or the scale bar, or whatever, I rearrange my figures until they look how I want them to look and that’s important because why bother doing all this work if I end up with something that looks like garabage?

Because of that small detail, my function is already very long, but it’s getting unruly. Normally if I want to redraw a figure I can just tell MATLAB what to do and it does it, but since my figures are all custom works of art (not serious), I can no longer do that. Instead I have to dig into the properties of each figure to find out where the stuff I want to change is located and change it very manually. This wouldn’t be a problem if it weren’t for the fact that I rely on several outside functions to draw these figures.

This is the part where I beg you, if you write some code, to comment the damned thing. Overly comment, write a small novel of comments, complain about the damn code in the comments, I don’t care as long as you explain what the hell you’re doing when you’re writing the code. Please. I am begging you, your code does nothing for others if you don’t bother explaining what the hell is going on inside. If you share your code someone will inevitably want to edit it to do something different with it and documentation within the code is important. This is the digital age, who cares if your code is now 600 Kb instead of 450 Kb all because you added some comments? There’s enough space on everyone’s hard drive for it and if there isn’t there is something else seriously wrong.

This rant brought to you by the code I had to disassemble with barely any hint as to what the hell it was doing. The story goes like this, I wanted to strip out the bit of code from this other function that did the thing I needed for my code. This way instead of calling that bit of code, I could do this very specific thing within my own code. It makes things easier to follow, it means I don’t have to keep calling this other code in very weird ways (because it would do something to my figures if I didn’t call it in a very specific manner, which was not intuitive) , and it makes it easier for anyone who isn’t me to figure out what I’m doing.

After a few hours I got the 10 or so lines of code to do what I needed, but not after disassembling the code and following it line by line to figure out what the hell it was doing and how to remove the chunk of it I needed. This is because code doesn’t always run linearly. I mean it does to a certain extent, but I could create a variable at the beginning of the code, do something with it in the middle, and then use it in the end to get my output. Tracking down what’s happening to several different variables in code that is larger than 1000 lines is a pain. What’s an even bigger pain is that almost all the things I needed where buried and obscured because people have this incredibly annoying habit with writing the smallest code possible, making it incredibly difficult to read.

Here’s an example. Say I wanted to write an if statement in MATLAB. An if statement checks to see if a statement is true and if that statement is true it does whatever is in the confines of that if statement. So it would look something like this:

if i == 10

        fprintf(‘Do a few things’)

end

Which is a dumb example, but it works. It says that if my variable i (not defined here, but just go with it) is equal to 10 it will print (fprintf in MATLAB will print a statement in the command line) ‘Do a few things.’ Writing it out like this for someone like me makes life easy because there is an indent with all the things inside the if statement that makes it easy for me to scroll through all those lines of code and catch it. Instead what people have tended to do, and what annoys me to no end is write the same exact code above as:

if i == 10, fprintf(‘Do a few things’), end

Which works. It does. It also shrinks the code down to one line instead of three, but it makes it so incredibly hard to read and find in all the various other lines of code. It makes no sense to do it this way, there’s literally no point anymore, we can write as long a code as we want and add in blank lines to make things more organized and easier to read. I often add what I call strategic blank lines to my code so you know where the breaks are. I also often add sections, which are designated by %% and add a little line across to make it easier to see where one step turns into another step.

All that to say, it took hours to do something that could’ve taken minutes had whoever wrote the code bothered to thoroughly comment it or at least didn’t attempt to save a handful of lines by cramming everything into one line. So please, don’t do it.

Now if you excuse me I have some horrible code to write.