There is this nice C compiler for the Radio Shack Color Computer now called CMOC. It’s not very easy to get it working under windows and and even with Linux or a MAC it has some involved steps to get it working.

I was recently watching COCO TALK Podcast #43 and they had a discussion about CMOC. Somebody asked if a nice installer existed for it but Boisy Pitre mentioned that it involved some other tools and things to be installed and that made it “complicated”.

This got me thinking… what it it could be a little easier? It got me thinking about a tool called Vagrant. It is a tool that can take advantage of Virtual Machine software like Oracle VirtualBox (which is free). It turned out to be not so hard.

STEP 1

WINDOWS:

Vagrant requires the “Microsoft Visual C++ 2010 SP1 Redistributable Package (x86)” to be installed if you are running Windows. Download it from https://www.microsoft.com/en-us/download/details.aspx?id=8328

Also, windows doesn’t normally have an SSH client… but GITHUB will install one.

In order to get an SSH client on Windows you can install Git. Git is used for version control, but
we’re interested in the SSH client that it ships with. Download git here:
http://mirror.linuxtrainingacademy.com/git/windows/

IMPORTANT: Tell the GIT installer to “USE GIT AND OPTIONAL UNIX TOOLS FROM THE WINDOWS COMMAND PROMPT”… for everything else, take defaults options.

STEP 2

Install VirtualBox from http://mirror.linuxtrainingacademy.com/virtualbox/

Load the right one for your particular operating system. Some versions might require a few extra steps… but the Oracle site has good documentation.

Accept defaults for the installation.

STEP 3

Install Vagrant from http://mirror.linuxtrainingacademy.com/vagrant/

Accept defaults for the installation.

STEP 4

Start a command line session on your local machine. (Windows “Command prompt”, Linux/MAC “Terminal session”

STEP 5

Add A BOX to Vagrant.

A “box” in Vagrant speak is an operating system image. The “vagrant box add ” command will download and store that box on your local system. You only need to download a box once as this image will be cloned when you create a new virtual machine with Vagrant using the box’s name.
I created a box specifically for this solution and uploaded it to the public Vagrant box catalog. Run the following command on your local machine to download it.

vagrant box add pwillard/ubuntu6809cmoc

STEP 6

To work with Vagrant, we need to create a working folder: “mkdir cmoc“

Next, we move to that folder: “cd cmoc“

Now we need set up out working environment in this folder: “vagrant init pwillard/ubuntu6809cmoc“

This will create the local files needed in this folder to refer to the BOX we will be using. So now, its time to bring up our virtual environment. The contents of the “Vagrant” file can be as simple as:

Vagrant.configure("2") do |config|
  config.vm.box = "pwillard/Ubuntu6809cmoc"
  config.vm.box_version = "1.0.0"
end

“vagrant up“

The first time you run the “vagrant up ” command Vagrant will import (clone) the vagrant box into VirtualBox and start it. If Vagrant detects that the virtual machine already exists in VirtualBox it will simply start it. By default, when the virtual machine is started, it is started in headless mode
meaning there is no UI for the machine visible on your local host machine.

It will do some steps and return to a command prompt. You can check status with:

“vagrant status“

If the machine is in the “running”state, you are ready to use it.

“vagrant ssh“

This will open a SSH terminal session to the Linux environment built into the supplied vagrant BOX file. You should see something like the following for a prompt:

vagrant@vagrant-ubuntu-trusty-32:~$

One of the nice features of vagrant is that you can have a shared folder between the vagrant Ubuntu machine and your host PC that is the folder you started the session from. This directory on your PC now has a file in it called Vagrantfile. This is the configuration file for your virtual Linux machine.

You should be able to “cd /vagrant” at the vagrant@vagrant-ubuntu-trusty-32:~$ prompt. You should also be able to see the “Vagrantfile“. If not, you might need to edit the “Vagrantfile” to contain the following line:

config.vm.synced_folder “.”, “/vagrant”, enabled: true

If you needed to add this line, then exit the SSH session, and type: “vagrant reload” and the “vagrant ssh“. You should now have a working shared folder.

With these steps done, you should have a system where you can type handy developer commands like “cmoc“, or “lwasm” or even “decb” and have them actually work. (You didn’t need to install them yourself)

Simple Ways to Write Maintainable Code

Writing maintainable code is something that comes naturally to some and only with a great deal of effort to others. It is within the ability of all programmers though – some just need a little encouragement to drop bad habits. I have been programming for many years now and I have seen a wide range of code which has differed in quality from the horrific train crash style code to the sun drenched gently rolling hillside style.

Over the rest of this part article I will try and describe what I, and many others, feel makes for good and maintainable code. None of the suggestions I will make here are difficult or time consuming to implement and will save many times the amount of time they cost. I am most comfortable when coding in Java so these guidelines have that language in mind. They are equably applicable to any language however.

Simplicity

Simplicity is, in my opinion, the key to maintainable code but simplicity means different things to different people. To me it means that within sixty seconds of looking at a piece of code you should have at least a vague idea what it does. Ideally you should be able to tell roughly what a method is going to do from its signature alone.

I believe simplicity also means avoiding use of obscure or difficult to understand language features unless they are necessary. No language is perfect; they all have aspects that the majority of developers rarely if ever use. Including one of these aspects is just asking for trouble when you or worse a colleague comes to maintain the code. In Java for example you can define static and non-static initialization blocks – how many developers that haven’t taken the Java certification exams even know this is possible? There is also the old ternary operator chestnut – the operator that code maintainers love to hate. I’m not advocating that your code should be the equivalent of a “Spot the Dog Goes to the Beach” children’s book, I believe it should be pitch at or just very slightly above the average developer.

If your code requires you to read volumes of documentation and then study each line in detail there is a good chance that it is too complicated. As with all these guidelines they are just that – guidelines. There are times when a method or piece of code just is complicated but you should aim to minimize these occurrences with good design. Use encapsulation to hide the complexity from the rest of the system and expose a clean and simple interface. Additionally, avoid the mistake of trying to hide complexity by producing hundreds of tiny methods. This is at least as confusing as trawling though one massive method that does all the work.

Aim to make your code as simple as possible and no simpler.

Comments

This will sound like a rather trite statement to make but comment sensibly. Too many comments are as bad, perhaps even worse, than too few. Too many comments and especially trivial comments will cause the maintainer to ignore them. All the effort put into writing the comments is then wasted. Instead comment blocks of code with one line that says what it does. If it needs more than three lines there’s a good chance it’s doing too much.

The one line comment in a method is useful because it means the maintainer can read that and have a pretty good idea whether they can simply skip that section when looking for a problem.

Method level and class level comments can be more verbose. Personally, I like to see thorough documentation of methods that actually do work. Simple getters and setters rarely get commented. Generally a method comment should not describe how the method does something only what it does. In practice if the comments are only intended for internal consumption it can often be useful to add a little information on how as well.