Thursday, June 15, 2006

Clean, Clear and Concise Code - part I

I can’t remember a programming assignment in school where somewhere in the list of requirements there wasn’t a point made about clean, clear, concise and commented code. That isn’t to say that sometimes you have to write some pretty large functions with multiple levels of nesting conditionals, but I would expect that there should be some hints to a future reader (possibly yourself) as to what you were thinking when you wrote the code. I think that more often than not, it seems that programmers get under a time crunch, and say things like “I’ll document later”, or “My code is so straightforward, no one will need comments to navigate it”. Maybe you are one of those types that is so brilliant you can remember every line of code you wrote and why you wrote it, but chances are, you aren’t and even if you can, what about the dude who will be picking up your code in a month or ten years, what then? Will that poor junior developer be able to quickly come up to speed with your code, or will he/she spend hours trying to figure out how to channel your chi to know what you were thinking when you wrote that triskaideca-nested(13) if then block, and what exactly it accomplishes.

Being the most junior of developers on a team, I am seeing a lot of different code, written by many different developers. Some of the code is relatively new; some of it may as well be archaic. Some of the developers took the time to carefully comment, others didn’t. Some observed a very consistent naming and formatting scheme, some code has been through some code has been through so many hands that it doesn’t have _a_ style.

I suppose that my point this evening is that I can sympathize with the need to get a project done, and I understand that reading code that you didn’t write is really the last thing that any developer really wants to do. Further, writing good code in a project that isn’t “yours” may also present you with a challenge, after all, if it isn’t your project why should you care what the code looks like? But you see, this is how the problem starts. Maybe you added 75 lines, that’s innocent enough isn’t it? Then again, the next developer thought the same thing, and before you know it, you’ve had hands all over the code, and it really is an unmitigated mess because no one ever bothered to think about maintainability in the long run. All the while, this code is doing important work, and it has been tried and true. It may be harder than hell to read, but it does the job. Perhaps you, sick of looking at that code would go to your manager and ask if you could just re-write the whole thing, but does that really solve the issue at its root?

Every developer that actually believes he/she is one would agree that the answer is a resounding no. The root of the issue is writing clean, clear, concise and commented code. It really is easier said than done, because writing code in this way requires some extra effort on the part of the programmer. It isn’t simply a matter of what gets the job done now, but also what makes for easy expansion in the future, is presented in the most simple and beautiful way, and will be understandable to anyone with reasonable coding skills sometime in the future.

I’ll motivate with a story from school. At the end of my sophomore year in school, my friends and I were taking a computer systems course. It wasn’t a full OS course, as we were just addressing small pieces as isolated units, but one of the most interesting assignments was to write malloc and free functions. Anyone who has gone down that road can attest to the fact that systems code of that nature is some of the most interesting, and non trivial code that a student can write as part of a classroom curriculum. Anyhow, our group of friends split into teams, and got to work. One of the guys was really into the project and coded up a skeleton malloc function and handed it over to his partner to complete the assignment. There was only one problem. This code written in C had no comments, and the variable names were un-intelligible to any person that wasn’t the programmer. One letter variable names, all pointers- in short a nightmare to anyone trying to figure out what was going on. As it turned out, my two friends had to be together in the same room to finish the project because the one who wrote the code had to be in the same room for the other friend to understand what he had written. Needless to say, we gave him an endless amount of torment over his coding style. He is extremely bright, gets amazing grades, works hard, and knows his code, but it was just impossible to read.

Fast forward a year and we are in a compilers course. This time it is just me and my super bright friend. We are working on the compiler together, but something changed this time around. He decided to comment the code, and use variable names that were intelligible. I don’t know what he would say about the experience, but I will still thank him for making it possible for me to understand what he was doing in the code. The final phase of the compiler the code-generator along with a register-allocator was some of the most complex code that we had ever written/seen, it was really cool at the end of the semester to see it actually working, and I don’t think I would have been able to do my part nearly as easily had my friend not taken the time to clearly document and write his code.

Yes, in the commercial world there is pressure to ship the product. Often the desired due date is yesterday, but I still do not believe that this is a ticket to write bad code. Every programmer knows what “spaghetti code” is, and at one time or another we have all contributed to the pasta bowl, but maybe now it is time to repent.

Wednesday, June 14, 2006

Two Steps Forward One Step Back

So I took the site a step backwards this evening. There were some things about the other layout that really weren’t perfected, and the more I saw it, the more it really started to grate on me. I am not really happy with what I have going on here either, but at least its degenerate cases aren’t as ugly as the degenerate cases on the “new” layout. I hadn’t considered what a simple thing like an add blocker could do to a site. That speaks strongly to the idea that everything should be driven completely by the HTML/CSS, I don’t want to follow that road too far though because that’s the same camp that says you shouldn’t use JavaScript either, and that is a proposition that I don’t think that I could tolerate. JavaScript is actually making the web useful as a realistic application platform.

So, I guess I need to go back to the drawing board and re-think how I will design this site. I really liked the simplicity of the design, but it was too reliant on sIFR. Of course, the folks who tout sIFR also remind their users that they need to have something that looks good before the original text is replaced, so maybe I will get to thinking about that. In the end, I want something that looks cleaner and more professional, but above all, it needs to work well for most configurations and not look dastardly just because someone has decided that flash isn’t for them.

When motivation strikes again, I’ll take a go at revising it again.

Saturday, June 10, 2006


So I have been reading blogs now for a little over two years. I know that this fact makes me a little tike in the grand scheme of the world wide web and this thing called blogging, but I feel that I have been around long enough to have some opinions on a couple of things.

When this adventure started, I was using Internet Explorer, and had this ever growing list of “favorites” that I would compulsively click through each day to see if the author or content provider had decided to put up something new. Toward the end of 2004, my school friends convinced me that I needed to give up IE and give FireFox a try. I was hooked on first download, and most impressed by the “live bookmark” feature, as it allowed me to check the blogs that I read only by hovering over the live bookmarks to see what was new. The downside to this is that you had to move your links with you from computer to computer, and sometimes the live bookmarks didn’t quite work the way that you would expect them to.

So, I tried various RSS aggregators and wasn’t pleased with the results as they all had quirks in them that I though represented compromises to the way I wanted to read “stuff” on the web. I had heard about some of the popular online RSS aggregators that were out there, but I’ll be the first to admit I am stubborn when it comes to signing up for a new service, so I didn’t.

The story gets interesting when Google first introduces Reader. It was around the same time that they were pushing Google desktop, and I was (and still am) disappointed with the idea that Reader and Desktop didn’t talk to each other as far as the feeds that they read, and dismissed both products in favor of the FireFox live bookmark.

Still, reading more blogs, and hearing about how Reader now has the ability to share, I decided to give it another go (no I still haven’t re-installed Google Desktop). This time around I have been completely wowed. It appears that the Google team has put a significant amount of effort into Reader since its conception. I am pleased with the way that it keeps track of my feeds, and very impressed with the ability that I have to share items with my friends. It really brings my blog/news reading to a new level.

When you get in there, you can take a look at my starred items, and also the starred items of my friend, Curtis. If you already use reader, and have a feed to share, let me know, I would love to see what you’ve been reading!

You too can harvest the power of feeds and sharing, give Reader a try today! If you still haven’t caught onto the great Google bandwagon and need an invite to get an account, I can help you out with that too.

Friday, June 09, 2006


Well, I have decided that it was time for the site to don a new skin today. It is more simple than what I had before. I am not sure if I am in love with it yet, especially the part about having photos at the bottom of the page, but it is different, and different is at least well... different. I haven't remodeled the about page yet, but that is sure to come in the future. We'll give this a go and see what turns out, if you like it, or hate it, or worse if I broke something, speak up and at least your voice was heard.


Monday, June 05, 2006

A Great Day

A day in which you can write programs, solve programming puzzles, take photographs, work hard, ride your bicycle, chat with your best friends, and eat good meals is a very good day. It isn’t every day that I get to enjoy so many of my favorite things to do.

I feel like I got a lot done. At work I only have a few hours left programming in no IDE land. Hopefully I can take care of that tomorrow morning. My legs are tired, and telling me that they got a good workout this evening. Wasatch drive was a lot more challenging than it was a week ago when I rode it last.

Things aren’t perfect, but tonight (and most every day if I really think about it) there is more to be grateful for than to complain about.

Saturday, June 03, 2006

I Finished!

For the first time in more years than I would care to admit, and certainly the first time in my “adult” life, I participated in a public sports event as an athlete. Though calling me an athlete is probably a bit of an exaggeration. Two months ago I said that I wanted to ride the Salt Lake City Bike Tour, which is an event associated with the Salt Lake City Marathon. I didn’t have a bike, nor had I ridden one in 6 years, but a Saturday morning trip to the bike shop fixed that in short order.

The event was a blast! The temperature was great, the crowd was excited, and the route showed off a few of Salt Lake’s most interesting neighborhoods. The parts of the course that I was most worried about turned out not to be so bad, I’ll chalk that up to the adrenaline of the event. In a place where I would normally travel at an average speed of 15-18 mph, I was riding 20-23. It was totally cool!

I blew out a tire on the course, and of course I was stubborn and hadn’t learned how to use my CO2 cartridge, and didn’t have a bicycle pump. It’s a good thing that my father and one of his work associates were on the course with me. They helped me get things fixed up, and I really couldn’t have finished had it not been for Dave’s bicycle pump!

It was a great event for a great day. Today’s distance/time was the farthest/longest that I have gone in this new re-birth of biking. I am pretty tired, but have a good idea of where I would like to go next. It would be really cool to keep working hard so that I could be in shape to do a century ride (100 miles). I guess that it just has to do with time invested in training.

Cycling is good for me. Not only is it something that doesn’t involve the rigors of writing code, or sitting in front of a computer screen but it’s also a great stress reliever. It is a good feeling to know that I can push my body to do things that it didn’t think that it could do. After the race, I was pretty tired, and felt like I wanted to vomit, my dad told me to take it easy and drink some water, Dave remarked, “Isn’t it a great feeling to know that you worked so hard you want to throw up?” I think that though it sounds weird, I think that the answer to the question is yes. Anyhow, biking is fun, and I hope that this is just the first of many future events! Maybe someday I’ll run the marathon, but for now, I’ll just be happy that I could bike it.