As developers, we have all experienced the spiking blood pressure of seeing a project with missing requirements, ill-defined scope, or outrageous objectives. But, as developers who rail against the project managers, business analysts, sales force, and others who are the root cause of many a late nights in life, how often do we think about our inefficiencies in writing code? How can you conceptually solve all the problems before ever writing a byte of code, and spend your time building instead of problem solving on-the fly?

The solution is so simple it’s almost insulting. Of course it took me a long time to develop this habit, but since I’ve begun using it I have shaved at least 25% off my average build time. As a further benefit, you will be able to explain why business owners need to go ask specific questions of the client, and do it in a non-technical way. If you are a team leader or senior developer, you can pass something useful down to the members of your team who will be doing the actual coding, and ensure they are building what you envisioned.

The solution is simpler then pseudo-code.

It is simpler then ‘stubbing’ your code.

It is even simpler then grabbing a whiteboard and drawing a diagram.

The solution is to Write your comments first.

Okay, so you’ve decided that I’m crazy. After all, how can you comment on something that’s not written?

The answer is that you’ve only been using comments half correctly – until now.

Let’s look at the following problem to solve:

You want your user to enter their birth date, gender, and shoe size. You then will tell them how old they are. Then, you will give them some generic saying. Depending on how old they are, you will give them different sayings. Depending on their gender, you will address them differently. Depending on the shoe size (small, medium, large), you will make some comment regarding podiatric hygiene.

Simple enough, right? Well, let’s use my approach to coding to make this even simpler and readable for a non-technical person, and able to be passed off to a team member to complete.

// State the goal of your snippet/program/object/etc
     // Depending on user input, we're returning various sayings 
     // and comments about the user

// State data requirements
     // user generated data - user age, user gender, and user shoe size
     // constant data - today's date, various messages returned, form of 
     // address specific to gender, age categories, shoe-size delineations

// State probable functions to write to achieve results desired
     // Determine user's age
     // Determine whether a user's age fits into a category
     // Determine gender specific form of address
     // Determine shoe size category (small, medium, large

// State the use of the probable functions
     // start return message with gender specific form of address
     // tell them how old they are
     // write witty comment specific to age range
     // write witty comment specific to shoe size

That took me four minutes to write, with minimal thought. That’s a four minute investment that allows me to:
1. Ask the business owner questions about age categories, shoe-size categories, and what
forms of address for gender – All not in the requirements

2. Ask the business owner about messaging – What the heck are the messages?

3. Define what my data needs are – I hate to get to the function writing and discover I need to declare something
I hadn’t thought of previously

4. Define what my program will be doing before the data is returned – It sounds dumb, but your thought process
probably doesn’t reach this until you’re half-waydone writing decision making functions. If you envision the
functions from the start, your solution will be more eloquent and scalable.

5. Define specific output – again, sounds dumb, but how many times have your written something and then
asked the business owner about phrasing, specific words, or layout?

All of the above, taken together, could represent many hours of back-and-forth with the business-owner, the client, and fellow developers. All nipped in the bud using 15 lines of comments. Furthermore, leaving those comments in after project completion will allow easier debugging later. Of course, I’d expect any developers to put in specific comments where necessary, but these comments form the framework of the code. There will be no question from my developers what they should do. There will be no question as to the thought process I went through when scoping this request. Most importantly to me, as I’ve trudged through the fields of murky requirements most of my life, the onus for results is pushed back onto the business-owner, while simultaneously establishing the main ‘chunks’ of this requirement.