One of our development team’s current projects is porting our network of web sites from Classic ASP to ASP.NET. All of our current scripts and apps are written in VBScript (of course), so when switching to ASP.NET, the obvious choice is to use VB.NET, right? I mean, our team already knows VB syntax and, as a result, we would find it easier to learn VB.NET.

That’s not the only thing that matters, though. The architectural differences between Classic ASP and ASP.NET are significant enough that knowing VBScript won’t in itself help us be great VB.NET programmers.

VB.NET and C# actually share a lot of similarities in terms of functionality. But that doesn’t make them identical. Google Trends tells me that, as of this writing, C# is 3 times as popular as VB.NET. That translates into a lot of extra resources for learning and troubleshooting.

This signifies the importance of hiring versatile programmers over <insert language here> programmers. With the latter, then you almost have no choice when refactoring; you’re pretty much forced to use the same (or similar) language, even when another language may be more appropriate for the job at hand.

The hard part about picking a language for a new project is determining if it’s the right tool for the job. That means figuring out the advantages and disadvantages of each reasonable option.

In our case, picking VB.NET over C# means that our team will probably be able to pick it up faster, and we’ll be able to get a version of our system released sooner. Yes that’s a very clear benefit, but using that as the only criterion to make the decision is akin to taking a loan without first asking about the rate of interest.

According to Alan Kay, the right language alone is not good enough. Language adoption is almost as much about marketing as anything else.

Let’s say the adoption of programming languages has very often been somewhat accidental, and the emphasis has very often been on how easy it is to implement the programming language rather than on its actual merits and features. For instance, Basic would never have surfaced because there was always a language better than Basic for that purpose. That language was Joss, which predated Basic and was beautiful. But Basic happened to be on a GE timesharing system that was done by Dartmouth, and when GE decided to franchise that, it started spreading Basic around just because it was there, not because it had any intrinsic merits whatsoever.

PHP is another example. I was talking to a former colleague of mine the other day about how easy it was for me to just start coding with PHP. Because it’s such a popular language, there are a lot of libraries and resources out there to do a wide variety of simple things. Its popularity also results in the community around it growing even further, which some might classify as progress:

There was a tight feedback loop as increased knowledge enabled us to discover and manufacture more tools, and these tools allowed us to discover and learn more knowledge, and both the tools and knowledge made our lives easier and longer. The general enlargement of knowledge and comfort and choices – and the sense of well-being – was called progress.

Of course, PHP gets its fair share of detractors, so I’m not even going to try to argue about how great or terrible it is. All I’m saying is that the fact that it’s popular carries with it some benefit.

Picking a popular language can reduce time to market, which may determine whether or not the project will succeed, while picking a maintainable language may allow you to last longer in that market. But if you pick too niche a language, it will be hard to find programmers who are skilled in that development environment, which means you’ll end up paying more for experience and/or training.

This is a decision that needs to be made at the project level, and it needs to be made with the right information, not just the information that’s easiest to gather.

In one of my most memorable software projects, our team maintained a strong focus on documentation, and it definitely paid off.

The five of us knew ahead of time that there would be only one version of the application, and the development time frame was relatively short (8 months of part-time development), so we followed a waterfall methodology for the project.

I know the waterfall model gets a lot of flak for leading to project failure, but we felt that it was appropriate for our project. The project actually turned out to be a great success, and I’m pretty sure that the methodology had nothing to do with it.

We had many deliberations up front about what features we wanted to include. I remember the meeting well: we brainstormed our ideas over a few pitchers of beer (you know, to get the creative juices flowing) and made a whole bunch of far-fetched predictions about how each feature would integrate into the system as a whole. I remember taking a minimalist stance, knowing there would be no version 2. I argued against implementing additional features “if we had time”. Any additional time would have to be allocated to testing and/or marketing (which ended up just being a nice glossy UI and a nice glossy demo).

Anyway, we used our requirements to develop a specification written in the form of use cases and non-technical requirements. It was about 40 pages, which seems huge for such a small project. The real documentation win came in the form of our 100+-page design document. We got it bound and everything. It was a real work of art, consisting of class diagrams, sequence diagrams, and state charts galore.

But that wasn’t what was so amazing about it. It’s what we did with it that counted.

I remember doing majority of the coding with the document at my side, using it to resolve differences between what I thought during the requirements and design phases and what I was thinking during the implementation phase. All five of us did this. We wanted to make sure that we built the system we planned to build.

The most amazing part of all was our vow to finish the project with all the documentation, coding, and testing plans in sync. So we went back and updated the requirements and design documents with anything we changed as a result of realizing we didn’t initially know what we were talking about. Then we got them bound. Again. We basically rewrote our own history.

The thing that mattered most was that we were all committed to documenting our communication, and then using that documentation for further discussion. We talked throughout every phase of the project. The whole experience taught me that communication is the key to project success. Cohesive documentation is just one way to ensure that the conversation is preserved, and that future team members can join in at any point.

In our small project, it wasn’t our choice of methodology that made a difference; rather, it was our attitude towards the methodology we chose.

I saved myself 27 minutes a week, and it feels great. It may not be a lot, but it was enough to stop a particular task from being a nuisance.

I work for a publishing company that uses a homespun CMS. One of the features we built is to allow editors to post polls to engage readers. A few editors do this on a regular (typically weekly) basis.

Anyway, the feature was first developed with the main goal of displaying the polls and collecting the responses. A poll’s question and choices are fetched from a database and the newest poll is displayed by default. Unfortunately, nothing was ever built to allow the editors to add new polls, so they would send the details to us by email and we would manually insert it into the database.

Shortly after I started in my initial position as a web developer, adding these polls to the database became my responsibility. The task overhead – receiving the initial email, opening the DB admin tool, switching to and from the email to copy and paste the values into the appropriate tables, checking that it worked correctly, and sending a confirmation email – was enough to make the effectively-ten-minute task a noticeable burden. I mean, for something that seemed like it should have been painless, I was really feeling it. After a few weeks of doing it this way, I decided to do something about it.

I started off by describing the project to my manager and asking for the go-ahead. The response wasn’t encouraging. He explained to me that, at some point in the past, they decided it would be faster to manually insert poll questions into the database than to build a tool for it. That was enough to make me forget about it. How weak of me.

But another few weeks passed, and I could no longer contain the temptation to improve the process. I took about an hour of downtime at work to write the necessary code and queries to simplify the whole procedure. Now I just fill out a three-field form to post the poll. Text, text, textarea, submit. It doesn’t even take a minute now, which is a 90% reduction in time!

I designed it mostly to help myself, but now it serves as a proof of concept to roll it out as a tool that the editors can use themselves. Of course, it will need to be user-friendly to have any chance of acceptance. Still, the expected benefits are there for both the development team and the editorial team: 1) it saves us time and – perhaps more importantly – pain; and 2) it will allow the editors to have greater control over the content on their sites and they won’t have to wait as long for the work to get done (it’s faster to find one minute in a day than ten of them).

The fact that I can take a manual process and automate a solution is one of the reasons I chose to go into software engineering, and I don’t think I’d put myself in a situation where I don’t have that kind of freedom.

As for this project, the next challenge is to gather support and feedback from the potential userbase: the editors. Doing so will put me in a much stronger position to make a case to my manager to back the solution.

After I wrote about why you should make your code more readable, I decided to take a snippet of code that I had just thrown together and rewrite it so that its purpose was clearer. The code is from a project that a friend and I built to help us learn about developing for the Arduino.

Original Code

In the full program, each time a pushbutton is pressed, a counter is incremented and shown on a 7-segment display (up to a max of 9). When the button is held for 3 seconds, the on-board LED blinks the number of times on the counter, and then the counter is reset. It’s a fairly simple program, but it definitely carried enough of a challenge to be interesting.

The segment below is responsible for blinking the LED.

int i;

for (i = 0; i < counter; i++)
{
  digitalWrite(ledPin, HIGH); //turn LED on
  delay(500);

  digitalWrite(ledPin, LOW); //turn LED off
  delay(500);
}

counter = 0;

The Re-write

I started off by renaming each of my variables to describe why it was there. We had been using the counter variable to store how many times the LED would blink when the button was held down for 3 seconds. Since a “counter” can really be used for any purpose, I figured it would be more descriptive to call the variable numberOfTimesToBlink. It’s a bit verbose, but it lets the reader understand what the code is doing without having to hunt for where the variable was declared.

The next step was to rename i. I thought about naming it something like numberOfTimesBlinkedSoFar, but it didn’t seem to carry any additional meaning. When I thought about it further, I realized that it was the variable that wasn’t carrying any meaning. The problem here was that I put in a for loop where it didn’t really make sense to have one.

Recognizing that I was resetting the counter at the end of the loop anyways, I figured it would make more sense to just decrement the counter each time through the loop such that it ends at its intended final value of 0. In the context of the loop, the variable now means “number of times left to blink”, which matches the way its named.

Final Code

while (numberOfTimesToBlink > 0)
{
  digitalWrite(ledPin, HIGH); //turn LED on
  delay(500);

  digitalWrite(ledPin, LOW); //turn LED off
  delay(500);

  numberOfTimesToBlink--;
}

I don’t have any metric available for “more readable”, but the modified code definitely carries more meaning in fewer lines. I asked a friend of mine to review the code and he agreed that the latter was easier to understand.

When I first wrote the code, it seemed like such an inconvenience. But in the end, thinking everything through really didn’t all that long. The lesson for the future is to always ask myself if my code can be made more readable, and if it can, then do it, either now or soon.

When you read an article on programming, most of the code samples are deliberately contrived. But the best samples have a common element: function and variable names very clearly describe their purpose.

That’s not a coincidence. The code is written so that someone reading it can figure out what it does.

But I’m guessing your code never seems to read so clearly. Your variables have shortened names and you type fewer comments because using fewer keystrokes means having a smaller chance of getting carpal tunnel. Your variables are declared where you think you might use them, even if you never do (I was shocked at how often I actually left them in the code, and I only realized it once I started looking at the warnings in Visual Studio .NET). And you never explain your logic because, well, someone can just ask you if they really want to know, right?

But when authors write articles, they are presumably writing them to be read. If nobody reads them, then their efforts have been wasted. That’s not quite the case with your code. Even if nobody reads it, it still does what it’s supposed to. And I suppose that’s fine if you’re writing code by yourself. Except it’s not really all that fine because you probably won’t be able to understand that code in a couple years anyway. My point is that if the code is written to be understood, then the code will be understood.

Good writers get paid well because they are good at communicating with words. Maybe developers should get paid well for communicating with code. A former professor of mine notes that “over half of the money and effort spent on the software product is spent during maintenance and evolution.” If you have code that’s been written to be read – as well as function – then maintenance costs will drop.

I feel like every code snippet written should be forced to be presented to the public. That way, the incentive to make code unreadable would just disappear. Maybe I’m being a little too hopeful, but it can’t all that bad an idea. I mean, if you have enough pride to rubber duck, then you shouldn’t be embarrassed to explain your code to a real, live human.

I tried this recently while writing some code for an open-source microcontroller project. I was working with a mechanical engineering friend who has a basic understanding of programming. We weren’t working on anything too complex, so I figured that he should at least be able to read the code, even if he wasn’t going to be writing it from scratch.

The code worked, but it wasn’t pretty, and he asked me to walk him through it. When I did, I found myself uttering words I didn’t really want to hear – things like “it could probably be made a little clearer” and “this is kind of a hack, but…”. He was right to suggest that this was why existing code was so hard to deal with.

Writing good code goes beyond merely getting it to work. It also involves considering how the code will be used in the future. Yes, it’ll be used by a computer, but the code also needs to be used by people:

You must consider the needs and capabilities of other people. For instance, if you are a programmer who refuses to be bothered to write readable code, then testing and maintenance of your code will be a great burden, if not an impossibility.

You can’t afford to be selfish when it comes to programming as part of a team. You need to show empathy, which basically means putting yourself in someone else’s shoes. There are plenty of examples of how not to care about the people who need to read your code.

So keep that in mind before your check-ins.

(Update: I decided to take my own advice and re-write some of my code to improve readability.)