Maybe we’re approaching this the wrong way

I have been thinking a bit lately about the process of coding. At this point I believe that there are two distinct phases: blank page and non-blank page. The “blank page” phase is when a new component is being added — essentially, you have a “blank” editor window. The “non-blank page” is slightly harder to narrow down, but in essence, it is the point at which you have something coded. (I’ll leave something undefined at this point.) The act of typing out language statements (i.e. “coding”) appears to be most effective during the blank-page phase. You will be hard pressed to find a WYSIWYG, drag and drop editor that allows a more rapid entry of logic and expressions. (Please note that I’m not saying that a drag and drop editor would be slower in cases of building up a class stub, for example. I’m referring to for loops or general if logic and the like.)

Code and coding appears to be less effective once something (still undefined) has been written — the non-blank-page phase. Attempting to understand large-scale structure and to perform change analysis is extremely difficult when just looking at code. Comments combined with code help facilitate change analysis quite a bit, but still fall short of a magic bullet.

Let’s approach this from a different angle. The primary reason for comments is to inform you or another developer of the intent, purpose, concerns, etc of the code so that when modifications or debugging are performed, all concerns and implications are known. (Please note that I’m only concerned with non-API defining comments in this disucssion. API comments are those only used by “external” developers to use an API.) In other words, comments aren’t useful in any way during the blank-page phase. Comments are only added to be useful in the non-blank-page phase.

If you think about a standard development hierarchy, more senior developers are doing the blank-page phase work (as well as some early non-blank-page work. This is where the ill-defined “coded something” will eventually derive its definition from.) whereas junior developers are typically thrown into maintenance (certainly non-blank-page work). This creates an environment whereby those that are least able to write effective comments are the ones that must be writing the comments. I say that senior developers are least able because they have had more time away from code maintenance and only by doing regular code maintenance does one know what are the most effective comments to write.

I’ve just thrown out a whole bunch of ideas that may seem orthogonal. I’ll summarize:

  • There appears to be two distinct phases of the process of coding: blank-page and non-blank-page.
  • The act of coding (writing language statements) appears to be best suited for the blank-page phase.
  • Code (the output of the blank-page phase) is ill-suited for the non-blank-page phase. Coding itself is of dubious use during the non-blank-page phase unless new features are being added (in which case, one could argue that this is a form of “blank-page”).
  • Comments provide important information that is not expressible in code.
  • Comments are of little to no use in the blank-page phase but are paramount in the non-blank-page phase. (Please note that I am omitting comments used for describing an API (e.g. javadocs) in this discussion.)
  • Comments must be specified in the blank-page phase and maintained during the non-blank-page phase (as part of the code maintenance).

All of this screams dichotomy. Code and comments, the output of the blank-page phase, appear to be the least suitable inputs to the non-blank-page phase. Code (“language statements”) is written since it appears to be the fastest way of “data entry” for the blank-page phase but code is not suitable for change analysis during the non-blank-page phase.

Couple this dichotomy with the average times spent in each phase. If you look at “pre-1.0” vs. “post-1.0” times (development time vs. maintenance time) you can see numbers like 1:2, or 1:10. In other words, maintenance time (non-blank-page phase) far outweighs the initial development (blank-page phase’ish) time. Yet all of our techniques, our “tools”, are best suited for the blank-page phase.

Perhaps we’re approaching code the wrong way.

For those familiar with the concept of Intentional Programming (IP), a light blub may have lit up. I’m actually talking about a level above IP. One can make the argument that Eclipse (with the AST) combined with the EMF (well, some yet-to-be-written instance of the EMF) provides for the IP paradigm. The problem is that an AST view of IP does not effectively incorporate comments.



  1. My guess is that you are talking about inline comments (as in not API comments, aka javadoc?). The phases you describing are valid, mostly “blank” page work is API definition and actual implementation starts off implementing interfaces which can be considered as a “non-blank” page work. I’d like to hear your opinion on what are the benefits of having inline comments? What should/should’t be put into inline comment? How you feel about people who actually prefer to read the code to make sure that comments do match the actual implementation?

  2. It seems that I’ve confused the point that I’m making by bringing in the concept of comments. Many people have thought that this entry is about commenting.
    I will approach this another way: Picture the last time that you were handed a big fetid mass of code with the instruction “fix bug XYZ”. Does the code (as a bunch of textual statements (we’re excluding comments at this point)) provide any assistance to you in your task? I’m sure that you’re thinking “It’s all I have” and “It completely describes the process and flow of the application” and I will certainly agree with you.
    But the question is: is there a representation that will enable you to perform your task more easily? I assert that there is on the grounds that the code itself does such a poor job. (No, this isn’t logically sound, but I’m an optimist. There -must- be a better way!).

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s