I was doing a few days coding for a client and informed them that I only had a few more free days before starting back into a new term at grad school and that I would probably not get much done given I was still learning the e-commerce package that they were using. But in order to provide them with a deliverable I decided to record my steps and thoughts in a document in narrative form for their future information and use.
There is much discussion about narrative verses symbolic code and moving computer languages more toward a natural language. Such is the discussion about Domain Specific Languages. However, when I say narrative form I am not speaking of actually writing code but rather simple prose mixed with code as needed, to record thought processes, research findings, and general steps in a discovery process. Here is an example layout of what I did:
Saturday, January 05, 2008
Login Test
Current Steps Planned:
I would describe the steps/tasks that I planned on taking for this date. It could include a list of items, a brief description of what is planned, etc. Actual steps:
Here I would describe the steps/tasks that I planned on taking the time.
Login Test
Current Steps Planned:
I would describe the steps/tasks that I planned on taking for this date. It could include a list of items, a brief description of what is planned, etc. Actual steps:
- Here I would describe actual steps that I took, thoughts in the process, rationale for decisions, etc.
- I added a check to the Customer.Authenticate method.
if (customer.ID[0].Status != Customer.Validated){
throw new CustomerException(CustomerExceptionType.NotValidated, "Customer Not Validated");
}
- This resulted in an error when attempting to login with the userid and password.
- ......
Here I would describe the steps/tasks that I planned on taking the time.
What I found was this forced me to be more precise in my thinking which naturally resulted in a more precise research and coding process. I have always known that writing makes one organize their thoughts more orderly in order to communicate more clearly. However, I must say I enjoyed the controlling aspect of thinking in a narrative format. It somewhat reminded me of the Test Driven Development in which you are controlled by getting the current test you are working on to pass with the simplest code. You do not have the opportunity to thrash around or run down this rabbit trail or that. You record your processes, organizing and analyzing your thoughts as you go, making sure you are focused and productive.
