When I am building something complex in php or jQuery, I tend to rough out a plan in my head and then let the code flow from my fingertips. While this works for simple functionality, I inevitably end up getting confused on larger operations. I get caught up in single events, loosing sight of what is happening overall. In these cases, I find it best to step away from the screen and physically write down a plan. The sooner I do, the sooner I am back on track.

Writing down a plan of action is a great thing to do, even for a small bit of functionality. Whether you write simple but descriptive steps in a text editor, draw a tree view, scribble out some Rainman chicken scratch, or take over your studios whiteboard, a solid plan of operations is a great tool to have. Here’s a few reasons:

  • It gives you a story with a beginning, middle and end. A majority of the time, functions need to work from the inside out. By going through all of the steps, you consider the entire situation, including conditional situations. You may still end up missing something, but it’s better than not being prepared for a really obvious and critical if/else situation.
  • It frees you to think of how the task should work, rather than how the code should work. Not only can this help you write clearer, more succinct code, but allows time to evaluate user interaction or expectations.
  • It is a great way to communicate the logic of the functionality with designers or project managers. This makes sure everyone involved in the project is in on-board with how things will work.
  • It will still be there tomorrow. If you have a brilliant idea on Friday, you might end up forgetting the point of it over the weekend. When you have a saved document with a plan, you can add in notes and all your bright ideas along the way.
  • It can be passed on and referenced. If you end up getting moved to a different project, or are out sick for a week because you drank pond water, another developer can open your document and reference your plan. They can quickly get ahold of the overall goal, see what has been done, and work towards goals that you have provided.

Your plan can range from simple to complex, but it should be through. Here is an example of a plan for an ajax image gallery:



Page Loads with rows of images
User clicks image
Is an image gallery currently displayed in a container displayed after image row ends?
  Fix Height of .container to current height
  Fade out `.gallery` element from `.container`, Fade in `.loading-spinner`, remove `.gallery` element
  Are there any image galleries being displayed on the page?
      Fade out all `.container` elements while animating their height to 0.
      remove them from the DOM.
      Add `.container` after image row with default height.
      Fade in `.loading-spinner`.



  Load images from clicked link with ajax, append images into a new `.gallery` element, add it to `.container`.
  Initiate slider on `.gallery`
  When images have loaded, animate `.container` height to match new `.gallery`, fade in new `.gallery`.


This is a practice I am working on integrating into my day to day development. I still start most things with only a mental plan, and sometimes it works just fine. But the bigger the project, the bigger the need for a plan, and that’s where I try to implement this practice as early as possible.

The next time that your code has you stuck, or you are facing a design with large scale functionality, take a step back, grab a coffee, and get out your pen.