The ramblings of Eric Seijo - Software Developer / Life Hacker

Developers - Be Nice To The Next Guy

Posted by Eric Seijo Wed, 17 Jun 2009 15:53:00 GMT

I have spent the last few weeks adding functionality and making changes to a legacy enterprise application. I ran across some situations that I had to workaround which prompted me to make this list of what I consider basic and standard procedure:
  1. Comment Your Code - I can't tell you how frustrating it is to spend an hour reading through hundreds of lines of spagetti code looking to find out what a specific object or variable does. Although I mostly get paid by the hour, I'd rather solve the problem and spend my time making improvements to the code base and the application. If some bit of code isn't self-explanatory then please take 30 seconds and write a comment.
  2. Name Objects and Variables Expressively - Although it is often a matter of semantics I find it not only good coding practice but good manners to name things appropriately. I can't count how many times I've run across a variable called "var1" or an object named "obj3" or a method named "myVarCon". WTF do these mean? What do they do?? One of the great things I've learned as a Ruby programmer is to express yourself and your intentions within your code. If you have a variable like number_of_hours_worked or a method named convert_us_currency_to_british_pounds they speak for themselves and clarify your intentions. Naming in this way can get a bit verbose but I really think it's worth it, if not for the developer writing the code, then for those that follow.
  3. Document Your Work - The Ruby on Rails framework has a great documentation system baked right in to the framework which makes this very easy. If you're working on an app in a framework that doesn't offer documentation you should still take the the time to document your work. In these instances I like to provide at the very least a README for each major section of the app so that developers that follow have some help getting up to speed on the application and code structure.

    For example, I just spent a day looking for a discrepancy in an enterprise payroll application where various employee's pay were randomly getting reported incorrectly. The pay was correct but the reporting after the fact wasn't. This company has 700+ employees spread over 16 offices and there were thousands of lines of uncommented spaghetti code to read through (see the previous two items on my list) and track values across. After a day of this all of the code seemed to do what it was supposed to but no solution or bug was found. I was talking through this with one of my developers and he mentioned that while running queries against the database ever time he ran an update query the value in question never changed. A light bulb went off and I said to him, TRIGGERS! Sure enough there was an update trigger on the table which (to say the least) set a pay percentage value back to a "default" value for an office location. This "default" value was something that was used years ago and had since changed. The problem was that none of us knew about it. Now, after experiencing this I have changed my standard practice when learning a legacy system to include studying and documenting each and every table in the RDBMS.
I've worked with and come after some great developers which have made the transition to learning a new project so much more productive and fun. Let's all think about and be nice to the next guy!

Leave a comment