You have an awesome software idea, a world-changing app, or you are given ‘something’ to build. What happens most often with that idea or project is usually the same. It involves grabbing coffee and snacks, getting your laptop out, opening a text editor and playing around with google until things start to work. After hours, days, or even months of frustration, a Stack Overflow post gives you a turning point and you start to see this thing you’re trying to build come to life.

Unfortunately, that scenario left out one very important step. A plan. A plan is easily one of the most crucial steps in creating a project but is often overlooked. Why? Because taking the time to draw or map out something you do not fully understand can be challenging and strange. Embrace that challenge and strangeness because it will make your life and your project better.

Just like many other non-software projects, the thought of going into a development stage without a plan is unthinkable. It is highly unlikely that a house, a bridge, or even a table would be built without some form of a sketch or plan. Yet in the software industry, it is quite common.

The lack of a plan often results in what looks like a Rube Goldberg machine (pausing here for the web search…. go ahead, you know you want to….). Basically, Rube Goldberg machines are systems that are overly complicated and yet perform a very basic task. For example, placing a marble on a track that triggers thirty-plus whirling wild machines just to make a piece of toast. They are cool and fun to look at, yet this is not what you want your Github repo to look like.

The best way to avoid a Rube Goldberg repo is simple; plan first, then code. It does not have to be in the latest greatest tool filled with trendy sexiness, it can be a simple diagram with boxes and arrows. The main point is to lay out the overall design and map out what actors (classes or modules) are involved and how they are related (methods, variables passed, etc).

One of the main ways you will benefit from having a plan is with one of the hardest aspects of software development, naming. Finding the right word for variables, modules, classes, methods, and all the other aspects of your code can get quite perplexing. By simply drawing a diagram and including all the actors and how they are related, you will be able to experiment with naming and see how the overall story of your code reads. Strange naming and conflicting meanings will be much more obvious which leads to easier changes when compared to failing tests and fixing bugs.

Fixing bugs and tests means refactoring. It is much easier to refactor a diagram within a few minutes rather than having to refactor your code, no matter how simple your project may be. With much of the refactoring and experimenting handled by the process of creating a diagram, this means less time thinking about what you need to write and quicker for you to bring your project to completion.

Bottom line: the development of your project will be more efficient because you will have clear documentation and a better direction of where you are going.

As we all know, code documentation is often handled at the end of a development cycle (if it is handled at all). We also know that almost every project will require a change or a fix. When that time arrives the importance of good code documentation will hit you in the face because you will stare at your code unable to remember what you wrote and, most importantly, why you wrote it that way. If you have no documentation, it will take a while to get your head on straight and remember why those decisions were made and what that darn method is doing. By creating a diagram, you will at least have that documentation to help you see the whole system, who is involved, and hopefully why. Life will be much easier. Period.

So now that you have read this, take the next step. Go out there and find a tool you like that can help you layout your plan by building a diagram. If you have an existing software system already, do yourself a favor and use this new tool to build a diagram of that system for practice. By creating a diagram of an existing system, you often find a more logical or efficient way to structure the code of that system.

Make this a habit for yourself. Always make plans for what you are trying to build. As time goes by and you become more efficient in making diagrams and planning, you will also become more successful at building software systems with good code documentation. Having a good plan is only one small step for devs, but one giant leap for software.