In my preceding post I said that writing requirements & specifications must precede the writing of code and they must be written in the source file. Stands to reason. If code has to be written, it must be for a purpose. The purpose must be known before writing the code that is expected to meet the purpose. Therefore, it can - and should - be recorded before coding.
But specifications, instead of being entered as documentation in source files, can be put down in far more useful form. They can be recorded as Executable Specifications. What are executable specifications? They are Unit Tests. Watch this exposition by Misko Hevery (from ~17:28 till ~ 24:00) for how to write Executable Specifications. BTW, the complete video is worth watching.
Showing posts with label Specifications. Show all posts
Showing posts with label Specifications. Show all posts
04 February 2017
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.
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.
Subscribe to:
Posts (Atom)