Coders Write Specifications

Coders write code. Should they not write down specifications like a darzi? Let me describe an example.

I go to a developer and say, "I want a routine that gives me the roots of a quadratic." (user requirement).

In less than an hour I get an executable "quadratic.exe". The developer asks me to run it. I get prompt a prompt: "Please enter a: ". The developer informs me what is "a" and also what the following two inputs "b" & "c" are.

       I enter 0 for "a" and 1 for "b" and "c". I get a divide by zero error. I am expecting the result to be       -1 (x + 1 = 0)
       I enter 1 for a, 0 for b, and 1 for c. I expect to get imaginary 1 (j1). I get a NAN.
       I enter 1 for a, 0 for b, and -2 for c. I expect 1.414. I get 1.414213
       ....

I did not get what I wanted. Should I be disappointed? No. What I got was a prototype.

Prototypes are very useful. They help to refine user requirements and specifications. I do that now. Also, I add that I require to have  a function that will compute the roots and return it in a structure. I then define the structure for the developer.

The developer should now put the requirement and specifications in the function header. And it should be done before making any changes to the source code. As a matter of fact there should have been a header for the prototype code.

Function headers, and file headers are not comments. Comments are post action. Comments are made by Commentators.

Function headers, and file headers are requirements and specifications. They precede the action. Acts need to have a purpose; a desired result. They need to be performed when required preconditions are met.

Cricketing example: Dhoni (or Virat) sees a ball coming at him. It meets the preconditions for a six. He knows the Specifications for the action he has to take. He takes the action. The result follows. The commentators watch the result and pass Comments.

Commentators pass Comments. Coders write Specifications.