Avoiding the over-engineering trap

Starting a complex project from scratch for the first time can be a daunting task for a rookie developer and even seasoned developers for that matter. There is something about that blinking cursor on a blank page in your IDE that send a small wave of panic right through to your bones. What if I start down the wrong path in architecting my classes? What are my fail-overs? How many classes should I make? What should I call my primary namespace? Why did I choose this profession?!?! 

Take a deep breath.

In my short time as a full-time web developer, I have adhered to some strict principles to guide the way I code and help other developers hopefully bypass the over-engineering phase.  For me, avoiding this phase was born out of necessity. Before I was a full-time web developer, I was in marketing manager, honing my skills as a coder on the side while doing my primary job. Being in that situation required me to code efficiently, and because I dealt with clients, explain our technology to them in the simplest form, which brings me to my first guiding principle.

If you can't explain the code to someone in 60 seconds, it is too complex

My primary goal when coding is to solve the problem at hand in the least amount of lines as possible.  Yes, there are times when the project at hand requires complexity and many lines of code, but in most cases when I examine code, I often find that it can be cut down significantly or parts refactored into another class.

Let's use a user registration flow as an example. I find it incredibly helpful to talk the flow out in comments before I write 1 line of code in my submitRegitsration method. 

// sanitize the form data (offload to validation class)
// make sure we have all required fields
// if we have any errors, send them back to the registration page and highlight the missing or invalid fields
// everything looks good. insert the user into the database (offload to user class) and log them in

Of course this is your basic user registration flow, but the registration method is laid out in such a way that every part that needs to be offloaded to another class for a specific task is kicked right back to the primary method after the task is finished. There are no 2nd and 3rd levels of routing between classes that can add complexity to troubleshooting should a problem arise down the road. 

An experienced developer may look at this and brush it off as being far too simple or that I am a novice coder, but one thing I have heard throughout my career is that any developer who has ever opened my code can understand what it is doing in a short amount of time, whether or not they full understand how it works yet. Which leads me into my next point...

Be predictable

It surprises me how many developers follow no standards when it comes to writing their code. One class can look like it was written by a completely different person than the next, using a database connection in a different way than the other, one uses object and the other arrays, and so on.

When I say my code is predictable, I don't mean it is written like everyone else's as there is no correct coding style that suits everyone. The behavior is predictable because similar tasks amongst my classes produce similar output. All my classes that perform data insertion into a database return the primary key for that newly created entry. All of my database validation classes return a true/false boolean, and so on.

When another developer takes over my code, looks at any method in my application that is prefixed as save(something) or get(something), they can be 100% sure that they will get the same type of data returned from all methods that follow that naming convention. 

Predictability not only saves other developers time who may pick up your code, but it also saves yourself time. Most developers are not focused on one project for a long period of time. 8 months down the road, you might look at the class you wrote after working on several other projects and say what does that do again? If the behavior is predictable, it will take far less time to get reacquainted with your code. 

 Coding styles and predictability take time to develop, which leads me to me final point.

Refactor, Refactor, Refactor

Over-engineering is not necessarily confined to experienced developers. In many cases, your most junior developers will be the culprits. They may have learned from a bad developer or just yet have the knowledge to express what they need to do with their code in the simplest manner.

If the code you are writing may be used across several applications, it should be opened up and looked at every so often to see how it can be improved. Developers often are terrified of looking back at old work because 6 months of on the job learning can drastically change how we code. 

When I first started at teamDigital, I was tasked with re-writing an application to clean it up. I decided I was going to move in the direction of  Object Oriented PHP as I knew the benefits, but never quite had the opportunity to implement it. When the re-write was finished, everything worked as planned, plus some extra features and I gave myself a quiet high-five at my desk for learning something new.

A few months later after I learned more about OO PHP, I dove back in to look at what I had written and discovered that it was over-engineered to the point that adding functionality was quite difficult. I set aside a couple days to refactor the classes to make extending functionality much simpler. Success!

Upon my 3rd look at the code, I wasn't quite as disgusted, but I noticed that much of the functionality that was still locked into this application, mirrored functionality we could use across all our applications. I again refactored and this resulted in a highly flexible, yet dead simple framework of classes that we now use as the base of all our applications. 

Many developers can write a lot of code and handle complex problems, but it takes a great one to write clean, flexible and modular code. Refactoring and following some set of standards can help guide you down the right path and make every developers' life easier who must work on and maintain your applications.