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.

Book - Programming for the Absolute Beginner 2nd Edition

Programming for the Absolute Beginner 2nd Edition by Jerry Ford

I was excited to see that a second edition of Jerry Ford's programming book was recently released.  It uses Just BASIC (all examples also compatible with Liberty BASIC) to teach the fundamentals of programming.

Jump to Amazon's link

Here is the table of contents.  :-)

1 Introduction to Programming
2 Creating Programs with Just BASIC
3 Creating Graphical User Interfaces
4 Working with Variables and Arrays
5 Making Decisions with Conditional Logic
6 Using Loops to Process Data
7 Improving Program Organization with Functions and Subroutines
8 Working with Text Files
9 Working with Sound and Graphics
10 Arcade-Style Computer Game Development
11 Debugging Your Applications