Legacy Code

I remember the first time I heard the term “legacy code“. It was said with the implication that it was old, disliked, awful, God-help-you-if-you’re-sent-in-there-to-modify-it kind of stuff. That’s not really what it applies to, however. In many cases it’s really just code that’s not the most current stuff. It could be stuff that the previous guy wrote that you have to modify. And this is where I currently find myself.

I’m working on a project where the code was an internal application used by the folks who put together the parts that they make. It’s about three years old, written in Java, and contains almost no useful comments. The code is most definitely not self-documenting. It was put together by a summer intern with little actual coding experience and is a real mix of working, non-working, and perplexing code. Just upgrading to the latest java development kit has caused numerous warnings and exceptions.

I talked with the boss about what he wants done and then proceeded to take stock of what I’m dealing with. The UI isn’t terribly complicated other than a large table with lots of data and a few buttons mixed into the table. There’s some interesting functionality built into it (the table) and I’m trying to figure out if this is the best way to present this to the user or not. I’ve got a lot of leeway on how to proceed, but the requirement that it be done fairly quickly and cheaply.

After looking through the code in some detail, I have determined that the overall state of it is fairly “hacked”. It’s clear that the previous programmer didn’t understand why he was doing some things, especially related to event handling, putting icons into buttons, and computer graphics. So, in other words, there’s a lot of unnecessary code. The rest of the code is filled with uncommented, obscure variable names that are used, but of course, leave no indication of their job.

So, what’s a coder to do? I’ve tentatively decided to start by creating a new UI. I’ve discover Jaxx, which, although it doesn’t seem to be undergoing any changes and needs some updating for the latest jdk, does have some nice functionality and can help me get my project going quickly. This wasn’t an easy decision either, and I’m still second-guessing myself, but I figure that I can probably redo the basic UI with another similar toolkit in a few days, if necessary, for the next release.

With the new UI in place, I’ve been grabbing components of the code from the legacy application and moving it into the new framework I’ve built. So far, it has been a few days worth of work and I’ve got a much smaller, cleaner code base to work with. Already, the graphics are working better and there’s some separation of functionality into proper classes.

I plan to continue to grab code for the guts from the current app while cleaning it up, and adding some #!*!$%& comments and documentation. My decision might have been different if the circumstances were different. A clean, logical, well commented and documented code base would have led me to modify the current code as is. Notes on what wasn’t working yet would have helped. Since there was no source control used, I can’t even be sure that I have the latest code.

Am I making the right decisions? I believe so. I’ve made great progress in very little time and I’m reusing the existing code, so I’m not reinventing the part of the wheel that seems to be working.

What legacy do I plan to leave for myself and/or the next person who takes over the code?

  • I will comment the code and not assume that it’s so beautiful that it’s immediately intuitive. I’ll likely be the beneficiary of this a couple of months down the road.
  • I will use some source control, so I can know where the latest code is and do release control.
  • I will track working and non-working functionality.
  • I will spend time to think about the best way to accomplish the tasks at hand by doing diligent research and design.

I hope that this will lead to more interesting projects in the future with the successful delivery of this one. Doing good work leads to more work.

On Your Watch

I try to avoid politics with people I don’t know, but here goes; we’ll see how many people I insult with this post.

First, let me say how much I hate most politicians. With some exceptions, and despite most of them starting out with good intentions, they end up as self-interested, holier-than-thou, self-righteous, dishonest, and dishonorable windbags. Like most Americans, I have a vested interest in the current election. After eight years suffering through the results of the Bush Presidency (financial crises, foreign wars that we started, declining dollar, skyrocketing oil, etc.), I, like most of you, am looking forward to a regime change.

It’s an interesting mix of people running for the top spots. On one side, we have Barack Obama, who touts the word “change” as if that’s all it takes to make everything in Washington work as it should. He seems to have a good understanding of economic policy (if anyone can really “understand” it) and is clearly a very smart man. His running mate, Joe Biden, albeit a “gaffe machine”, has been around Washington long enough to know how it really works and can give Obama an earful on the foreign policy experience that Obama lacks.

On the other side we have John McCain, decorated war veteran, who served his country with distinction. He’s a smart man as well, and clearly cares for his country. He’s more “old school” on some issues, like maitaining troops in Iraq to ensure long-term stability. However, his plan to give more tax cuts to the wealthy (like Reagan’s and Bush Jr.’s trickle-down economics) and health-crisis plans (“we’ll assemble the best minds in the country”, gee, why didn’t anyone else think of that?) are clearly out of touch. His negative campaign has been thoroughly disgusting. If he wants to win any votes, he should run on his positive image and his policy plans. And, if he really cares about his country, he should end the divisive retoric in his messages. His running mate, Sarah Palin, while likeable, is clearly out of touch with the world. Who would have thought that she’d be tapped as a V.P. candidate? Clearly not Palin or she might have picked up a Time magazine, read it, and remembered what it was called.

Our current President dug himself into so many holes due to his own hubris, ignorance, and lack of respect for the opinions of others. While he didn’t bring down the World Trade Center, his administration had clues of attacks that were ignored. He didn’t make risky loans to homeowners, but he was in office making sure that his rich friends were well looked after, got all of the appropriate tax cuts, and had little oversight in the process. He clearly wasn’t responsible for invading two countries (Irag and Afghanistan), but, oh wait, that was all him, wasn’t it? Yes, it all happened on his watch.

How does all of this apply to you and me? It applies in several ways. First, it’s our responsibility to choose the next people to run the country. I can’t tell you who will do the better job. I can only implore you to select the people who are smart, won’t repeat the mistakes of the past, and will keep an open mind to changing the status quo. It also wouldn’t suck if they could pronounce nuclear properly (it’s new-klee-ur, not new-kya-ler).

Second, when you see things that are screwy in your own life (at work or home), you have the responsibility to make recommendations to the powers that can do something about them. If you’re the manager who has the power and you know something is going on in your own group, then it’s your responsibility to make it right. Turning a blind eye and hoping it will go away or somehow just work out, will not make it so. What happens is on your watch.

Will Code For Food

A couple of years ago I was looking for work in the Ithaca, NY area. Several people helped me find local companies and gave me moral support along the way. I ended up working for a small company that subcontracted me to a very large local defense contractor. It was a great experience on many levels. Since I left that job about a year ago, I’ve been working on some smaller personal projects, including my book.

Since I’m the most recent person amongst many former colleagues to go through the job search process, I’ve become the local go-to person for help with resumes and local companies. It’s a “job” that I happily do to help out my friends and neighbors. Recently a friend of a friend came here from India after a several year hiatus from coding to take care of a sick parent. His name is Joe Pierce, like most other folks from India that you speak to over the phone. I never met Joe or even spoke to him. I told my friend to have Joe send his resume to me so I could think of what local places he might look at and see if I could give him any good contacts.

When I received his resume and cover letter, it was a disaster. It covered three (!) pages and consisted of nine mostly short-term (e.g. 4 – 6 month) contract jobs over a twelve year period. Two things were painfully obvious looking at it. One, it was too long for such a short time period (a resume should be only one or two pages). Two, Joe was over 60 years old.

I’m not suggesting that being over 60 is inherently bad, but this is what he was presenting to a potential employer: I’m 63 years old, haven’t worked in 6 years, and most of my jobs have lasted around 4 months. Age discrimination may be illegal, but that’s no reason to stick it somebody’s face either. I suggested several changes:

  • Remove the years that he went to school – turns out this is becoming a common practice.
  • Highlight the skills he has in a good summary.
  • Shorten the whole thing to a page or two.

He was hesitant to take away the dates or change to a functional resume (people thought he was hiding something – he was, of course). On the other hand, your chances of anyone giving this guy a second thought are fairly slim. Your first job in job hunting is to get your foot in the door. You do this by having an intriguing resume and getting to the hiring manager, rather than the HR department. Once you get an interview, it will become very obvious that you’re old or young, short or tall, skinny or fat, American or not. None of these things should matter at all, but first you have to get to the interview. After that, you have the opportunity to present yourself in the best light possible and hopefully that comes out in person. You show up on time for the interview, you’re knowledgeable on the subject matter, and you seem like you’ll fit into the personality of the company.

Looking for a job is a full time job. Like any other job, you have to do some preparation, studying, and practicing to do it well. Get some good books out of the library (e.g. What Color Is Your Parachute), hit some good web sites (I recommend wandercoding.com 😉 ), and use your network of friends and former colleagues to help. Don’t dawdle – it’s your new job.

Epilogue: Unfortunately, unable to find work after 3 months, Joe returned to India.

You Write What?

When I meet new people, they inevitably ask me what I do for a living. I usually tell them that I write software (when I tell them that I rob banks, they often don’t believe me). Some people understand what that is and some don’t. It’s like the t-shirt I’ve seen that says, “There are 10 kinds of people in the world – those that understand binary and those who don’t.” The ones that do understand software might ask me what kind of software. The others just say things like, “You gotta be smart to do that.” While that should be a prerequisite for writing software, it’s not universally enforced, and thank goodness for that because some days…

Now, when I get in longer conversations, I also tell people that I’m writing a book about software – more specifically about software career related items (a lot like this web site, and no, it’s not just a collection of the blog posts contained herein.) A while ago, it occurred to me how similar writing a book and writing software are.

Creating an outline for a book is like planning the features for your software. Writing the text of a book is like writing the software. You even get syntax highlighting (spelling and grammar mistakes) pointed out by your integrated development environment (Microsoft Word, Star Office, WordPerfect, etc.) QA and bug fixing comes in the form of proofreading. Beta testing comes when you get other people to read what you’ve written and see if it’s logical, solves their problem(s) (even novels solve the problem of boredom or provoking thought), or provides a proof of concept. Then, when you’re done, you have to try to sell the book/software. Books, however, have traditionally been first sold to a publishing house, which is supposed to weed out the unpublishable. This is not a flawless plan, however. Some books are published that are boring as h**l and practically useless. Classics such as Jonathan Livingston Seagull, Lolita, and The Diary of a Young Girl (Anne Frank) were rejected by numerous publishing houses. Software used to have a similar avenue of distribution – you’d have to find stores to carry your software or advertise it in magazines and catalogs that catered to the end-user crowd.

Nowadays, publishing software is easy – just post it on your website for download. Book publishing has easy alternatives, too. Print on demand technology allows writers to bypass traditional publishing houses as does electronic publishing. In both books and software there is risk. Both require commitment, belief in what you’re doing, and a desire to overcome obstacles. The results are almost always unpredictable and what keeps life interesting and exciting. More to come…, wish me luck, buy the book (when it comes out in a couple of months).

The Forest and the Trees

Here are a couple of definitions for you. According to the Merriam Webster dictionary:

Strategy: noun, A careful plan or method.

Tactic: noun, a device for accomplishing an end.

These definitions work perfectly for talking about software management. When I was a manager a few years ago, some of my colleagues told me to stop worrying so much about the tactical and start worrying about the strategic. First, I had to stop and think about what they were driving at. As a software engineer turned manager (without much training in management), my approach was often to keep an eye on the code, what the people were doing with it, and how they were doing it. I was very good at helping solve problems that arose, coaching developers, adding some code occasionally (when I had time), and understanding what we were developing and why. For most engineers who move into management, this is perfectly normal and can be very effective. This is tactical thinking – what steps do we take to get from where we are to were are going.

What I wasn’t as good at (at least not then) was taking a step back from the day to day activities and looking at things as a whole. Do we have the right tools? Are our goals clear and correct? Are there more global changes to be made, such as schedule changes, personnel changes, feature scoping, etc.? Sure, I was good at some of these things, but not all the time. I would often get my head buried in the day to day operation of my group and not take the time to step back and look at the big picture. Looking at your overall goals is strategic thinking.

One thing I believe is lacking in many organizations (certainly in the places that I worked) is quality management training. Yes, I took classes in the legal aspects of management, how to develop a schedule (fine for waterfall methods), and how to communicate effectively. However, so much of management is fuzzy, and some new skills are required. How much time should you spend on various activities? What is your priority as a manager? What’s the best tool for scheduling and how to use it most effectively (MS Excel, MS Project, Rational, Visio, something else)? How frequently should you meet with your team members, colleagues, and manager? What’s the proper proportion of time to spend on various management activities? For example, some managers spend so much time in meetings, they never learn anything about your software and never know what is really going on. Then they’re surprised at inconvenient times to find out what the actual situation is.

In future posts, we’ll address some of these things. For now, whether you’re in management or not, take a step back and take a look at what you’re doing. Stop worrying for a minute about your current problem and ask if you’re even solving the right problem. Are you worried about the tree when you should be thinking about the forest?

Same S**t, Different Year

For the past few years, I’ve been playing fantasy football. If you’re not familiar with the concept, you join a league with some other people, pick a name for your team, and then draft players from the NFL. There’s an order for picking players based on your record from last year and each NFL player can only be chosen by one team owner. Your score for each game against another team (usually one “game” per week) is based on the yardage and scoring that your players contribute to their real NFL teams.

I’ll be honest – I’m a pretty good owner. I’ve won the title once and come in second twice. My success is based on a sound strategy:

  1. I pick as many good running backs and wide receivers as I can early because they tend to score more points on a weekly basis.
  2. I pick the best player available at the time. The best player available is determined by what is recommended by a couple of sources (magazines and web sites) as I figure that they probably know more than I do.
  3. After each week during the season, I look for trends in the past couple of weeks to see if there’s an undrafted player who is really producing that I can pick up and I drop one of my non-producing players.

One of my opponents in the league follows a different strategy. He arms himself with all of the same kinds of data that I have. Then he follows hunches and drafts players way too early (when they will probably still be available in later rounds), thereby wasting his good picking position. He ends up with a good picking position (much better than mine) because he’s always finishing in the bottom half of the league. So, not only does he have a bad strategy and bad results, but he never seems to learn from his previous mistakes. Of course, luck is involved in this game. Injuries will take your best players out for weeks or even the whole year. The best running back in the league will have a crummy offensive line and get nowhere. The NFL coach will let your running back do all the yardage work and let some guy come off the bench to score all the touchdowns. However, even with all of this, a sound strategy, a good bench, reacting to the situation, and contingency plans can keep your team in the playoff picture.

After draft night last weekend, I got to thinking how similar this was to my last product at a former company. Every release we would get a feature set, spend a couple of months designing the features, do estimates based on our design, argue over the validity of our estimates, and end up with a feature set that just fit into our time allotted. The end of the development cycle would come up right at the end of the year, just before the holidays and the week off we were supposed to get. The end of the entire release (bug fixing time) would coincide with the company’s flagship product which we were supposed to ship with. In other words, we were set up to work under stress with little margin for error. Inevitably, we would start to run behind, have to work through the week off during the holidays and go through a death march, working nights and weekends, for four months until we shipped. We had a bad strategy, poor contingency plans, and never seemed to learn from our previous mistakes. Before the next release, we’d say, “Well, we’ll just have to do a better job designing and estimating this year.” It’s a classic waterfall development cycle without any room for error, and no contingencies built in.

In previous products, we might use the waterfall method, but when time was running out, we’d be able to drop a feature to keep the release process sane. In any software release, you have the three main variables built in: time (including people, so person-hours), quality, and functionality. Things work best when there’s flexibility in the quality and functionality parts. The powers that be usually don’t like to ship extremely buggy software, so there’s only so much flexibility on the quality end. If you aren’t willing to drop any functionality, you expand the person-hours. Given that you usually have a set team size (and don’t forget that adding people to a late project doesn’t usually help) that means simply working more hours. As appealing as that sounds to upper management, especially those who haven’t written software in years, working tons of overtime doesn’t help as much as you might think. The garbage that gets written after you’ve been working for ten or twelve hours in a day is truly staggering. I frequently came in the next morning wondering what on earth I was thinking when I wrote that code or fixed that bug the night before. Essentially, I wasted hours of my life and didn’t help the project any.

If your release cycles are going the same way, take action sooner than later. Be willing to drop functionality as the release falls behind (lots of features are extraneous “nice to haves” not “need to haves”). Use a different release cycle process – will an agile process work where you are? Push the ship date back – many (but not all) ship dates are simply chosen out of thin air. When you push back at management or marketing, sometimes you’ll find that these dates really are flexible. The worst thing is to keep making the same mistakes over and over again. Can you get better at designing and estimating? Sure you can. Will it ever be perfect? Unlikely. Do some companies succeed this way? Sure. Has yours? Chances are that it hasn’t, which is why you’re still nodding your head as you read this.

Fuzzy Front End

In Steve McConnell’s excellent book, Rapid Development, he talks about wasting time during the fuzzy front end. This is the time of a project when you’re waiting for the new specifications to come from product design or marketing or whoever does the up-front design work for your product (or web site, etc.). After a release, especially an intense one, it’s natural to need some slow time. Keeping up a high-intensity pace on a permanent basis leads to rapid burnout, which isn’t very productive in the long term.

So, what can you do and what should you do? Here are some ideas for you next time you run into this time period.

  • Clean up time. Go through your code and find all of the crappy stuff you wrote because you didn’t have time to think it through clearly. Rewrite it the way you really should have.
  • Fix up the buggy back end. How many bugs didn’t you fix at the end of the previous release? Now’s a good time to fix the low hanging fruit or the ones that seemed too risky to attempt just before release.
  • Design time. What would you like to see your system structured like in the future? Can you design it differently to accommodate the expected feature set? Will some new designs make it easier to add new functionality?
  • Toolkit time. Do you have a lot of semi-repetitive or duplicated code in your system? Is it time to take these routines or classes and create a toolkit from them that can be called by the rest of the system?
  • Prototype time. As long as you don’t get too possessive of your new code, can you develop a small prototype for some expected new functionality? If you do, show it to the designers and see if it affects their thoughts on how something might look. I have long thought that the developers of a product can make excellent designers if consulted early and often during the design process. Are your developers actually the designers of your product? Great, but having someone be the overall supervisor of design work can make your product more consistent from a look and feel standpoint and can coordinate possibly redundant development work.

The fuzzy front end doesn’t have to be a waste of time. Your developers can be more productive if they have a clue of what might be coming and what’s expected of them. Making sure that they know that possible functionality isn’t cut in stone will help ensure that time and effort isn’t wasted on completed functionality before the details come out. Setting some clear goals for the fuzzy time can help keep them focused on using the time to their advantage and keep them from going crazy while waiting for the action to begin.

Measurement and Precision

About 15 years ago, I worked for a large engineering software company. While I was attending one of their corporate conferences, I met John, who was instrumental in the development of one of their products. He told me a story about the beginning phases of their new product when they were making architectural decisions. Back then, memory wasn’t the commodity it is now. The product ran on UNIX workstations and you had to be far more conscious of memory consumption and data structure sizes than most applications do today (although we might all be better off if people gave it a bit more consideration). The product worked with Finite Element Analysis (FEA) for analyzing mechanical and structural designs. As you might imagine, this kind of mathematically intensive work could use a lot of numbers and the precision of the numbers would affect both speed and accuracy of the analysis. John was adamant that double precision was required for accuracy, but was overruled by a manager, who was not technically oriented. Months later, when the analysis results were proving to be inaccurate, someone asked who made the precision decision. Someone blamed John, who was understandably quite livid about being blamed for the decision he had fought against.

A few years later, I was working on a solid modeling product for architects. I was mentoring a colleague, Sharon, in the ways of solid modeling and general application development. In order to do some of our calculations, we were using a vector class created by our graphics guy. As such, the vector math was being done in single precision as that’s what was common practice for graphics. As you might guess, when some of our modeling operations came out poorly, I asked Sharon to convert our code to use a double precision vector class. She was sure this was not the problem, but as I was the project leader and her manager, she did it anyway. Lo and behold the problems disappeared and she learned a valuable lesson.

Perhaps you, too, will have to make some decisions like this in your software development. Before you jump to conclusions, especially when it comes to something that’s fundamental to your product, do some experiments on size, speed, and other measurable performance. Err on the side of flexibility, if all other parameters are equal. If your language supports creating your own data type (such as a C++ typedef), you can delay the decision and change it later. If you believe that someone in your group is making the wrong decision, say something. Be sure to say it nicely, but say it and record it for future reference. When the fecal material hits the rotating air circulation device later, and someone picks you as the scapegoat, you’ll be able to say you did what you could. Better still, however, is to prevent the mistake by proving that the decision is incorrect by backing it up with hard data and keeping it objective and not personal.

Immersion

I just returned from Judo Camp yesterday. It’s a week of immersion. The schedule is brutal enough, but adding on an extra class on coaching makes it even more so. There’s a total of 5 hours of mat time, which includes a bit of warmup at the beginning of each of the three sessions. I’m accustomed to practicing only 4.5 hours per week and I’m usually sore during that, so you can imagine what camp must do. Add an uncomfortable mattress, evening socializing time, and an early wake up call – all amounting to massive sleep deprivation – and you have a recipe for true pain. And yes, I pay for the privilege of attending this.
I got home yesterday, said hi to my wife and took a three hour nap. I woke up for a while, had dinner, watched Phelps win his 8th gold medal, then slept another 8 hours.
While not nearly as exhausting, it reminds me of the times that I have attended software conferences in the past. They, too, are days of total immersion in the ideas behind coding. The best part is that you get to stop actually coding for a week and clear your head. Then you get to start thinking about what you’re actually doing. Are you using the latest tools and techniques? Is there a toolkit or add-on library that can help you with what you were doing with reams of your own code?
It’s not just conferences either – books, magazines, and blogs can give you another perspective on what you may be doing that’s less than efficient. Take some time now and then to pick your head up from coding and look around at what you’re doing and how you’re doing it. Go to lunch with your colleagues and manager and see if you can find some improvements to the way you’re working.

Whatchoo Say and Whatchoo Don’t

If you read my post Truth In Advertising, then you know how much I “love” commercials. Advertising is about what you say and don’t say. For example, there are two current commercials that feature bits of songs. The first is a cruise line that plays “Lust for life” by Iggy Pop. They only play the part that says, “Here comes johnny yen again, Got a lust for life, Yeah, a lust for life.” But, that’s only part of the song and actually it’s a mash of two different parts of it. You can see the complete lyrics here: Lust for life. I’ll give you a preview:

Here comes johnny yen again
With the liquor and drugs
And the flesh machine
Hes gonna do another strip tease.
Hey man, whered ya get that lotion?
Ive been hurting since Ive bought the gimmick
About something called love
Yeah, something called love.
Well, thats like hypnotizing chickens.

Why don’t they play that part? Or how about another commercial that plays R.E.M.’s “I am superman”? They play the part that says, “I am superman and I can do anything, I am superman and I know what’s happening.” But, they leave out the next lines:

You don’t really love that guy you make it with now do you?
I know you don’t love that guy cause I can see right through you.

I am I am I am Superman and I know what’s happening.
I am I am I am Superman and I can do anything.

If you go a million miles away I’ll track you down girl.
Trust me when I say I know the pathway to your heart.

I can’t imagine why.

Clearly there are reasons to leave this stuff out of their ads – mainly, they don’t add to the message they want to send. Let me tell you another short story along similar lines, this time related to software. A friend of a friend sent me his resume so that I could point him to some local companies that matched his skill set. Before I did that, I felt compelled to point out a few things about his resume – the main thing being that it was blatantly obvious based on his college graduation date that he was over 60 years old. While age discrimination is illegal, can you prove it if you simply don’t get called in for an interview? Heck, I’ve sent my resume to job listings that practically say, “Bill, this job is tailor-made for you” and never received a phone call.

So, my response was: remove those dates. If he managed to get an interview based on his skills and experience (the important stuff), then someone was bound to notice that he was, shall we say, life experienced. However, he’d have gotten in the door and could then convince them that he was the right person for the job. There’s room on your resume for what you’ve done right in your career. There’s no need to add what you haven’t done right and no need to supply detail about things that are detrimental to you being hired. Your resume is your own advertising brochure and the lyrics to the song about your own life. (Does that sound corny or what?) It’s dishonest to change they lyrics from programmer to CTO, but it’s not dishonest to remove a few details that may prove unflattering. For example, let’s say you got fired from a job a few years ago. Is it dishonest to not put that on your resume? Of course not. There’s no precedent for putting reasons for job departures on your resume. Similarly, while dates of employment may be important to have on your resume (employers are wary of gaps), there’s no reason to let people age you and it’s illegal for a potential employer to ask you your age.

Polish up your personal brochure and have a couple of friends in the business look it over with a critical and constructive eye. Nobody’s resume is perfect, but it should be the best advertisement you can make for the best product – you.