Thinking Backwards or Forwards

I've heard references to a new style for documenting requirements. Greg Young talks a little about it in his post on business requirements at CodeBetter.com



I think he is onto something, as it is usually fairly obvious that business customers can handle some pretty complicated procedures and process flows, so why do they struggle with a machine, or state, based approach?  The difference I suspect is that they focus on the action and not the state. The specs he describes are centered around a state, lists an action and only then describe the behavior that results from said action; let's write it thusly:




State ->Action->Behavior.



I'd be willing to bet that the users are really thinking like this, "I want it to do X (Behavior) so I have to push the yellow button (Action) but it only works if the red light is on (State), or



Behavior<-Action<-State





The style of documenting has enough in common that they understand what is being asked for even if, to them, it is listed backwards. As an aside, another major difference is I've never had a business user ever want to have a meta-discussion on how they think, so we tend to have to take it into account when designing the requirement gathering process but that will have to wait for its own post.

Computer Science is an Art

Of the many eternal debates that spiral around software development blogs the one that seems the most intransigent is whether the practice of programming is an art or a science.

Chefs have a similar discussion over cooking and baking.  Cooking is an art while baking is a science.  Why?  Because when you put something in the oven, you had better get it right the first time.  Mistakes mean starting over.  Cooking, on the other hand, allows the chef the leeway to make changes as the dish progresses. The chef can take action to keep the dish from heading off course. For example, when making gravy you keep adding flour until it is the right consistency and if you add too much flour you can add some milk to thin it down.  It is incremental by nature.

Programmings Best Kept Secret

Software development is often compared to engineering or construction which has a hidden and debatable assumption that the source code is the product.  One camp has declared that source code is the design .   Other camps declare that programming as a branch of applied mathematics; see Dijkstra's "uncomfortable truth" quotes. Extreme Programming as a movement may have failed, it at least served as the flashpoint for a new examination of the nature of programming. Instead of arguing about engineering we can brag about how Agile we are or that we are Software Craftsmen.

Programmers are not engineers, nor are they artists.  Even when they are compared to craftsmen,  the comparison is always with woodworkers or blacksmiths. Programmers are nothing of the sort, programmers are writers.  Danny Thorpe discusses how you might tell what sort of literature your app may be.

Danny is on the right track but when it comes to software, there is an elephant in the room that needs to be discussed in the open.  Developers do not produce software, they write code.  This means that sometimes they need the logic skills of an engineer but just as often they need the communication skills of a poet.  Reading and writing, thinking about how to achieve a desired affect through the written word, those are the qualities of a writer.  It just so happens that the one of the chosen audiences is a single-minded overly-literal pendantic polyglot idiot-savant, otherwise known as a computer.  The other audience is other humans that may or may not have to actually follow the instructions, they do have to understand them well enough to tell if the instructions are correct.


It would be useful to compare programming to other fields and see how the comparison holds up.  It is not a coincidence that the games industry has adopted the filmmaking model for the production of games. Good choices would be publishing a book, producing a movie, or creating a recipe.


Programming as publishing


Programmers are the authors.  The compiler is the printing press.  Publishers are the companies that agree to fund the process in hopes of turning a profit.  Self publishing would be like creating training manuals for internal use; no profit is involved but the medium is appropriate for other reasons.  The book still needs to be edited, proofread, typeset, marketed, etc. I've covered this ground before but there is still much to contemplate.


Programming as filmmaking

Filmmaking is in interesting comparison because it deals with translating the written word into another medium. Programmers are the writers of the scripts and screenplays.  The producer is the stakeholder who desires the software. The director is the project lead.  Instead of actors and crew  we have the compiler which takes our instructions and executes whatever script of commands we provide; call it a screenplay or call it an application, the actions and actors my be different but it's still a set of commands given to actors to be performed.



Programming as cooking

Programmers create a recipe for a given dish.  The recipe is not the final product, the result of following the recipe is.  You don't buy a cookbook for the fabulous chocolate cake recipe, you buy it because you want to eat the cake.  In this case the compiler would be the tools available to the chef; pots and pans, utensils, and the stove/oven.  Having the right tools really helps but even the best oven won't correct a recipe that calls for 2 cups of vinegar for the sugar cookies.  Eventually software may survive the patent wars and finally be considered on par with a recipe; instructions to a cook in order to produce the desired product.

Summary

Software is  actually a mix of disciplines, all trying to contribute towards a common goal. The game industry may have it right, evidenced by them being to busy producing games and not endlessing debating whether their process is broken or seeking the latest silver bullet.  They use directors, producers, art and sound specialists, etc.  The compiler is their camera, used to capture the intent of the contributors; the CPU the silver screen for which to project the final product for consumption by the audience.

Software as Literature

Alternative title: Sonnets to CPUs

Have you ever noticed that code follows some basic patterns? JUnit uses Setup(), Test(), Teardown().

I’ve playfully mixed writing and coding below.

---

//[Play about A Monarch's Destiny, in three acts]
Public KingdomFuture tellTheTaleOfMyRule(Kingdom landMyFatherLeftMe)
{
   //[1st Act:  Build Drama]
   Vassal mySubjects = SoliloquyAboutMyKingdom.getMyPeasants();
   Boolean mySubjectsLoyalty = testOfLoyalty(mySubject);

   Vassal theCaptainOfTheGuard = SoliloquyAboutMyKingdom.getMyTrustedRightHandMan();
   Boolean myTrustedServantsLoyalty = testOfLoyalty(theCaptainOfTheGuard);

   KingdomFuture historysTaleOfMyRule = KingdomFuture.UNDECIDED;

   //[2nd Act: Drama plays out]
   if ( mySubjectsLoyalty == TRUE 
        && myTrustedServantsLoyalty == TRUE)
   {
       HeapPraiseUpon(theCaptainOfTheGuard);
       historysTaleOfMyRule = ExpandKingdomByForce(mySubjects);
   }
   if ( mySubjectsLoyalty == FALSE 
        && myTrustedServantsLoyalty == FALSE)
   {
       ArrestTraitor(theCaptainOfTheGuard);
       historysTaleOfMyRule = ImposeDispicableLaws(mySubjects);
   }

   //[3rd Act: resolve drama]
   if ( deceptionHiddenSuccessfully(theCaptainOfTheGuard) )
   {
       return oldRulerOverthrown;
   }
   else
   { 
      return historysTaleOfMyRule;
   }
}

What Did You Say?

This says it all. Most of the time research focuses on if new stuff is possible. The real 'Silver Bullet' would be to find a way to solve the communication problem. Click on the image to embiggen.

Risky Words

Taking a break from the book review to post something small but still significant.

Clarity is a very useful tool to manage risk. If something isn’t clear, we’re at risk of getting something wrong. Many times your best risk management tools are your own ears. Nuance in language can be fun when you're flirting with someone at a bar, tossing out double-entendres but when preciseness or clarity is valued, like in requirements specifications, nuance can be a killer.

Review - The Psychology of Computer Programming

I got a "new" book in the mail a few weeks ago and finally had time to crack it open, "The Psychology of Computer Programming" by Gerald M. Weinberg published in 1971. There is a Silver Anniversary edition that recently came out but I wanted a cheap copy in hardback so mine came from an online used book site. Why read a computer programming book that is almost as old as myself? Because it addresses the core issue of producing computer programs, the people who read, write, edit, maintain, or otherwise cuss at (other people's of course), code. People are the primary factor in all programs; before hardware, language, specifications, anything. If you don't understand how humans go about creating these abstract entities called programs, you will constantly be mystified by missed deadlines, frustrated by missing functionality, and stymied by endless scope creep. Enough of my pontificating, let's talk about the book.

Table of Contents

1. Programming as Human Performance




1. Reading Programs


2. What Makes a Good Program?


3. How Can We Study Programming?




2. Programming as a Social Activity




4. The Programming Group


5. The Programming Team


6. The Programming Project




3. Programming as an Individual Activity




7. Variations in the Programming Task


8. Personality Factors


9. Intelligence, or Problem-Solving Ability


10. 1Motivation, Training, and Experience




4. Programming Tools




11. Programming Languages


12. Some Principles for Programming Language Design


13. Other Programming Tools




5. Epilogue

"Computer programming is a human activity." A pretty bold thesis from the intro to Part I. Is there a mystique to programming? "Either you can program or you cannot. Some have it; some don't." Both quotes give you a good idea as to what is in this book, tackled expertly by Mr. Weinberg.

Chapter 1 - Reading Programs

Some years ago, when COBOL was the great white programming hope, one heard much talk of the possibility of executives being able to read programs. Weith the perspective of time, we can see that this claim was merely inteded to attract the funds of exectutives who hoped to free themselves from bondage to their programmers. Nobody can seriously have believed that executives could read programs. Why should they? Even programmers do not read programs.

I hear a similar story from when assemblers were introduced - as in, "With the development of assemblers, we won't need programmers anymore!" I believe similar statements have been propagated by hordes of 4th generation language and CASE salesmen.

"Programming is, among other things, a kind of writing."

This is not a very mainstream view in the programming world even though we work with constructs which are literally "languages".

"We shall need a method of approach for reading programs, for, unlike novels, the best way to read them is not always from beginning to end. They are not even like mysteries, where we can turn to the penultimate page for the best part -- or like sexy books, which we can let fall open to the most creased pages in order to find the warmest passages. No, the good parts of a program are not found in any necessary places -- although we will later see how we can discover crucial sections for such tasks as debugging and optimization. Instead, we might base our reading on a conceptual framework consisting of the origin of each part. In other words, as we look at each peice of code, we ask ourselves the questions, 'Why is this piece here?'"

The author begins examining a section of PL/I code showing how certain machine, language, and human limitations influence a program. Machine limitations like lack of memory to hold the entire problem set in memory at the same time causing the use of two loops instead of one. Language limitations like the lack of an end-of-file indicator which forces the operators to include a special character (or card in the 1970's punch-card centric world) and causes the programmer to account for the special character in code. Programmer limitations like not really understanding array notation of the language, in this instance PL/I. As a program is modified over time, machines change, languages are updated, and programmers come and go.

"And so, some years later, a novice programmer who is given the job of modifying this program will congratulate himself for knowing more about PL/I than the person who originally wrote this program. Since that person is probably his supervisor, an unhealthy attitude may develop -- which, incidentally, is another psychological reality of programming life which we shall have to face eventually."

Some programs have inscrutable logic like the use of special characters which are ordinarily invalid; "magic numbers" used for interim states for some long-forgotten problem.

"Once the patch was made, it worked so well that everyone forgot about it -- more psychology -- and there it sat until unearthed many years later by two archeologist programmers."

To different versions of the same PL/I program are compared, the first includes many limitations of which we've already spoken, the second much improved by removal of the previous limitations. Of the comparison,

"When we look at the difference between Figures 1-1 and 1-4, we might begin to believe that very little of the coding that is done in the world has much to do with the problems we are trying to solve"

Would we be any better off if we could use the latest code (Figure 1-4) as our spec?

"Specifications evolve together with programs and programmers. Writing a program is a process of learning -- both for the programmer and the person who commissions the program. Moreover, this learning takes place in the context of a particular machine, a particular programming language, a particular programmer or programming team in a particular working environment, and a particular set of historical events that determine not just the form of the code but also what the code does!

In a way, the most important reason for stufying the process by which programs are written by people is not to make the programs more efficient, more compact, cheaper, or more easily understood. Instead, the most important gain is the prospect of getting from our programs what we really want -- rather than just whatever we can manage to produce in our fumbling, bumbling way"

Hopefully the reason to study a 30+ year-old book is apparent; those who fail to learn from history are bound to repeat it.

Let's study historical mistakes so we can make our own new mistakes instead of repeating mistakes of programmers long-retired.

The rest of the book is just as rich in lessons we can still take to heart. By approaching the book chapter by chapter, I'm hoping to increase my chances of getting all the way through without writing a 50-page article all at once which would never get finished.

Here is the link for the next chapter: Chapter 2 - What Makes a Good Program

To Function or Not to Function, That is the Question

Question:
What is the difference between a functional and non-functional requirement?

Answer:
If a requirement uses a verb to describe the feature then it is functional; What will the system *do*? If a requirement uses an adverb or adjective to describe the feature, 'how' will it do whatever, then it is non-functional.

I've almost always been interested in the importance of language in discussing requirements. There are two ways to listen to your customer, literally and figuratively. That the customer has difficulty describing their requirements has been a problem in the software field for so long that it's now a cliche. What some analysts have done in to start reading between the lines to capture what the customer is "really" saying. There can be some benefit to this figurative approach but I would always to to listen to them literally. In many cases this meant inconsistent or confusing descriptions, the key was to realize that those questionable points were just that, points to question. In getting clarification about those requirements, we can get a more detailed understanding of the problem domain. If their choice of words or phrases contradict, ask them about it.

Sometimes we need to listen figuratively or "between the lines" to get the overall picture but listening literally can be indispensable for uncovering the things you need to dig into for more details.