Have The Courage to Declutter - Best Practices Series

The things in our homes each have their own purpose, and they have their proper place.  In the course of time there is the inevitable accumulation of things, and this can become clutter which is a problem.  This is a way to think about programming.  It is not a perfect metaphor of course but I think it is useful.

Clean Your Room and Take Out the Trash

Living is a messy affair.  We do all kinds of things in our rooms.  Things like eating, opening and reading mail, getting dressed and undressed, play video games, etc.  If we don't stop and put things away and throw out the trash our rooms will unlivable.  How can we apply this when programming? First all if you find that you are commenting out code (in some languages comments are called remarks) then after a while your code will become harder to read and maintain.  Similarly if you notice you never use some part of your code any more it might be a good idea to delete that code.

Be brave and delete the old code.  If you want to keep the code then save the file in a different name so that you won't lose that version of it.  If you are using some kind of source code control (also known as version control) then you will never lose old code.

Don't Be a Hoarder

Hoarders are afraid to get rid of things and they often have many of the same kinds of things until their house fills up with so much stuff that they can't find anything and there is no room to live in their house anymore.

How to implement this idea in programming?  Each idea should only be expressed in one place. Do you notice sometimes when you're writing code that you are doing the same thing again and again so that when you change something then it needs to be changed everywhere you have that similar code?  You need to create a subroutine or a function that does that one thing in only one place, and then call that routine from all those places where the code was duplicated.  This is a kind of code refactoring.

Live In a Tiny House

Imagine your program must fit in a constrained memory.  What is the purpose of this, you might ask?  Today we have what is essentially unlimited memory in our computers.  If you just sat down and wrote code every day for the rest of your life you would never be able to fill up all that memory.  You might not be able to resist the temptation to add every single feature that you can to your software.  People who live in a tiny house often ask themselves what are the essential things, and what can be disposed of?  The more features you have, the more code you have, and the more complicated it is, and this makes it harder to extend and maintain.

    -"Everything should be as simple as possible, but not simpler." -- Albert Einstein

I hope this article is helpful to you and will give you something to incorporate into your work.

One Role Per Subroutine/Function - Best Practices Series

If I write the following code:

  call openFile "myFilename.dat"
  call writeDataToFile
  call closeFile

I have three different subroutines that I am calling.  The first call should open a file name named myFilename.dat.  It should not do anything unrelated to opening that file.  The writeData call should only write data to the file.  The closeFile call should only close the file.  These subroutines might have some related code that makes sense for dealing with files specific to the application, or some debug logging code or the like and that would probably be fine.

But if sub openFile also opens a graphics window, or if it reinitializes a bunch of variables, or anything else that is not directly related to opening the file, that code is probably in the wrong place.  Such code should be moved to its own subroutine.

Why is this important?

One important idea in software development is called the principle of least astonishment.  As much as possible when I read code I expect that it should do precisely what it appears to be doing.  Nothing more, and nothing less.  Trying to avoid "What the ..!?" moments is an important goal in programming.  It saves time and money and makes people's lives easier.  :-)

Sometimes code is initially written very clean and in a way that is compatible with this idea of one role per subroutine or function but over time it gets polluted and things get into the code which violate this principle.  This is especially common when debugging because it's easy to write code during a heavy debugging session that you would not normally be willing to write when you're not debugging.  Then once the bug seems to be gone we are less willing to move that 'debug quality code' to the place where it belongs, or we are not sure how to do it.

Of course if you write a program such that there are no named subroutines or functions then your program is in danger of being a Big ball of mud (see https://en.wikipedia.org/wiki/Big_ball_of_mud).  If you discover that this is the state of your work, your code can be greatly improved by beginning to identify sections of code that can be moved into named subroutines or functions.

As a counterpoint this idea if you find that all the programs that you write are small one page long games or utilities that you bang out in a few minutes, then your programs might only be a small ball of mud.  In this case you might not really benefit very much from trying to break everything down into small named subroutines.

Naming Things Well - Best Practices Series

Some BASIC programmers come from the experience of needing to fit their programs in 4K of RAM or less, so it feels natural to give variable names single letters such as a, b, c or I, j, k. Of course most classic BASIC interpreters don't have support more for than 2 characters for variables. Some BASICs will let you call your variable 'count' but only the c and o will be recognized as the variable name.

To be fair, I've seen more than a few C programmers also choose single character variable names. Bad habits are language agnostic. ;)

In programming languages today including Liberty BASIC, you can give your variable names and other things such as subroutines and functions longer names. What's more, computers have so much memory that we can dispense with trying to save memory with short variable names. And if you're used to using line numbers I strongly encourage you to discard them in favor of named labels. Once you are used to this it will make your programming better.

Why does it matter?

Programming is an exercise in thinking and so it is really important to pick the best possible names for the parts of your programming ideas. When you or somebody else reads your code it will help to understand the code if the variables and function/sub names are chosen well.

What if you are about to go to the store to buy some milk and you told your friend "I'm g to the s to b some m." How well would you be understood?

So, when you write code ask yourself (or the coder next to you) what is the best name for this variable or routine? Later on you may even realize there is a better name and so don't hesitate to act on that impulse and update your code with the new better name.

Think of your coding as a journey to discover the truth of the code, and naming things is an important part of the discovery.