Maintainability and Code Organization

Thursday, December 8th 2011

I really like programming computers. As I grow older in my profession, I really like reading source code that I can maintain. Maintenance must be our primary concern when we write our code. Because, someone else will need to change it, one day, and they’ll have to understand it.

Most of the dev blogs that I read talk about solutions and patterns. I value those topics highly. I like to know what other folks not bound by the chains of big IT have created. However, when they talk about object-oriented code, I sometimes sense a mysticism about it. When others write about functional programming, I sense an even stronger transcendentalism.

But, let’s distill the nonsense away and talk about the real motivation for object-oriented programming: better code organization. Partitioning the behavior of the system into logical containers that manage the data on which the behavior relies, that’s object-oriented programming. We can communicate our ideas of related behavior better with a named class like Car than a set of files that contain functions that work on a CAR structure.

With that said, please follow some simple rules when writing your code. It’ll make those that did not write the code appreciate it all the more.

  1. Let’s keep our lines within 80 characters. I know this seems a little 1970s. However, go look at a book. Go look at almost anything created with TeX. Our eyes crave narrow text flow. We can parse information better that way. And, since source code contains almost 100% information, we need all the help we can get when reading it.

  2. Favor composition over inheritance, espeically for DRYing code. Inheritance hides the contract that our object will expose to the system. Too much of that will make the reader have to retain too much knowledge to comprehend your implementation. The “Extract Method to Superclass” refactoring pattern will almost always lead to trouble. We should, instead, “Extract Method to Helper Class.” C# developers, that does not mean public static.

  3. When you hit 500 SLOCs for a class, that might be bad design. In an interview, I once asked the candidate, “How big of a method is too big.” He thought for a moment and replied, “When it’s bigger than my head.” I smiled. “You mean when it’s too much for you to understand at once?” “No. I mean if I hold my head up to the screen and the method is longer than my head, that method is too big.”

  4. Practice the Law of Demeter though it hurts. Badly. I hate to comply with the Law of Demeter. I have to type a lot of boilerplate crap. I don’t like it. Not one bit. Because every SLOC I write could have a bug. But, darn it, LoD will ensure that I can look at the code and know exactly on what it depends. And, the code that uses that class will only know that class. It’s the Principal of Least Knowledge at its finest.

  5. If you write unit tests, practice writing unit tests. We have spent a lot of time honing our craft as programmers. We learn how to use different libraries, languages, programming paradigms, methodologies, and more. We continually make our OO design practices better. But, a lot of programmers have immature testing styles. Practice that unit testing until it becomes second nature. Patterns exist, there, just like in OO. Discover them.

  6. When you mix language paradigms, do it consistently. A lot of hybrid languages now exist, those that mingle aspects of procedural, object-oriented, and functional programming. If you decide to use those features in your code, make sure to do it consistently. I recently worked on a .NET project where the major contributor “discovered” .NET “lambdas” about halfway through the project’s timeline. After that event, almost every method took a lambda of some sort. Half of the implementation used OO, the other used the half-ass functional programming of C#. Messy. Plain messy.