Day 26: Write About Your Problem

Problem solving is a very individual process. Everyone has a preferred way of thinking about problems, and as a result they come up with their own methods and strategies to find solutions. Programming is similar in that there are several ways of solving any design or implementation issue. It is also a singular field in which developers spend most of their time solving problems.

This leads to the necessity of cultivating problem solving strategies in the programming field. Most programmers have a crystalized process that is used frequently for solving similar classes of problems. Many of the differences between programmers have to do with how effective their solutions processes are. That is why I think that discussing solution techniques is a very important part of becoming a better programmer.

Writing as an Exercise

One of my preferred methods for problem solution is to use the old pen and paper to write down solution possibilities. Unlike most people who like to draw diagrams, I think that writing words that convey meaning about the problem is the shortest way to understand and finally figure out a solution.

Writing has several advantages, but they are compound when it comes to software development. First, software creation is mainly a symbolic manipulation activity, in many ways similar to writing. The software creation process certainly has its peculiarities, but it  involves describing the problem at a level that can be understood not only by computers, but also by human beings.

Another of the advantages of writing in the initial phase is the opportunity to build up a vocabulary. Playing with words to explain and try to find potential solutions for a problem can help in building this vocabulary in a quick and effective way. Later on, this might be helpful in identifying key elements such as classes, methods, use cases and other components of the system.

Writing During Initial Design

The design phase is the part of the development process where writing plays an obvious role. First, when designing you will want to convince not only you, but probably your boss and other members of the group that your approach is viable. In this phase, you will be interested in creating a formal document such as a technical spec for the work that will come.

Even if a formal document is not necessary, it is a good idea to create something polished and presentable. The reason is that this will become necessary eventually. Even when working on your own projects it will come a time when you need to explain the design to someone else. Having a design document can greatly simplify this communication effort between you and other developers.

Having a technical spec can also be of great help for yourself, because it may serve to clarify issues that would not appear otherwise. For example, if two or more systems need to cooperate for your design to work, a spec can help you clarify the roles for each component of the system. This way, you can refer to the resulting documentation whenever you’re ready to work on the implementation.

Writing as an Implementation Strategy

Another good use for writing is as part of the coding process itself. During this phase, one is interested not only on what will be done, but in the exact details of how some programing task can be accomplished.

A few people have perfected this kind of coding strategy. The best known of them is professor Knuth from Stanford. He was the creator of the literate programming technique, which is based on a simple idea: first write one or more paragraphs describing whatever a section of code is supposed to do and how it will be accomplished, then present the source code that achieves the desired result.

The great advantage is that, by writing first, you are thinking about particular issues that the code will have to deal with. Once you start writing the code itself, the whole strategy will be well developed. While doing this takes some extra time, depending on the complexity of what you’re implementing it may be a net win. I wouldn’t spend this energy to write software that I already know how it is supposed to work. On the other hand, writing complex functionality may benefit from the extra care, and literate programming can be a big win in this case.

Writing for Debugging Purposes

Debugging can also benefit from good, organized writing. The typical problem during a debug session is to track the reason why some unexpected event is happening. That may include things such as a crash, or a value that is printed incorrectly. Whatever the erroneous event you are trying to debug, it is easier to trace the causes if you write down the known reasons.

It turns out that writing a few paragraphs about how a bug happens may be the key to find its solution. The reason is that by writing about the problem you need to put the known facts in a logical sequence, and that sequence is frequently the key to understand how a bug is triggered. Composing a good description of how a bug is happening may provide all the elements necessary to pinpoint where the faulty code is.

For more complicated cases, I like to add some description of the involved code and the methods in the stack trace — if one is available. Then, it is possible to write down the sequence of events happening in the application from the point of view of the code being executed. Of course, I don’t need to do this for every bug, since it is a time consuming process. But for bugs that are difficult to solve, writing seems to be better than spending my time aimlessly staring at code.


Writing is a great way to make concepts clear both for you as well as for other people. As a development tool, writing has been explored by several programmers. For example, it is a major part of techniques such as literate programming. However, you don’t need to change your programming strategies to benefit from writing as a planning method. Just put your thoughts on paper, giving proper names to concepts, will increase of capacity of analyzing problems and uncover bugs even before they hit your code.

Similar Posts:

About the Author

Carlos Oliveira holds a PhD in Systems Engineering and Optimization from University of Florida. He works as a software engineer, with more than 10 years of experience in developing high performance, commercial and scientific applications in C++, Java, and Objective-C. His most Recent Book is Practical C++ Financial Programming.

One Response to “Day 26: Write About Your Problem”

  1. Totally agree.

    In terms of design, the process of distilling ideas into a clear, concise document solidifies them in your own mind, reveals contradictions, omissions and other issues.

    I also like to use scratch paper when working through elusive bugs. I’ve been laughed at for this, but it works for me.

    By Bruce on Mar 30, 2012

Post a Comment