Formal specifications, when to use? Do we have any actual standards?

Question

When we specify "simple" algorithms (short stretches of a system) for other programmers to develop, we can give some tips on how to Implement, put or take details that can help or hinder modularization or generalization of the solution, etc.

I know there are techniques, tools, links and methodologies... But I know that most require culture, standardization, and, above all, a certain familiarity with mathematics on the part of the whole team, something almost impossible to imagine in Brazil (!). The question is "What technique/methodology/framework most used today to specify critical algorithms?"

---

---

NOTES

The bureaucracy (of a somewhat more formal specification) has a price, but I am assuming that I wish to pay this price by demanding high reliability (e.g. banking or hospital applications) and/or performance (ex. mobile or real-time devices) result.

Naturally, sub-questions will arise (examples),

• "At what level of detail should I stop?";
• "I must use a second, higher-level language to specify?";
• "Does Javascript lend itself as a specification language today? Can I use advanced concepts such as map/reduce in the specifications that everyone will understand?"

---

There is a whole branch of Software engineering to suggest appropriate methods to "express what we want to other programmers"... And a part of that branch is the call theory of formal specifications. There are methods that start from diagrams UML until arriving at a stub of the class, method or function... But the focus on this question is really the algorithm, the hints of how it works or how it should respond to inputs.

All these considerations are theoretical and vague, I think we all need more practical and objective responses to day-to-day decisions with an average team of developers (no math training).

Context

This jsFiddle shows my experiments with jQuery.makeArray(), the native functions map() and reduce(), and when they are more elegant than a loop each() or for common... Has an HTML context, etc. and even a (real question associated), so we can use case example.

Grants for responses and discussions

To use more objectively the jsFiddle cited, let’s imagine that I want to specify the average of the text items of an HTML page.

Specification can have multiple levels, from free text to mathematical models...

• Level-1 (free text): show in Bold the average of the red items.

• Level-2 (HTML-focused technical text): show the average of class="m" in a paragraph below, in Bold.

• Level-3 (technical text assuming jQuery team and prefixed layout): average items $('.m') assuming integer numbers, placing the result in $('#r1').html().

• Level-...: routine to average the values of $.makeArray($('.m')).map(function(a){return parseInt(a.innerHTML)}) ...

• N-level: create simple (lightweight) routine, highly reliable and maximum performance; to average the values of A=$.makeArray($('.m')).map(function(a){return parseInt(a.innerHTML)}), that is to say, A.reduce(function(a, b){return a+b;})/A.length. Put the result in $('#r1').html().

Answer 1

I have always worked in companies in the financial sector, although the nature of the systems varies greatly.

In my practical experience, I find it almost impossible to define a general specification model that meets all cases, formal or otherwise.

For example, in an accounting system, a mathematical model would be more confusing than helping to specify critical parts of the system. However, the developer needs a basic training to understand the formulas and accounting process. The specification and examples are often made using spreadsheets, which many counters are familiar with, so it is possible to interact in a "common language".

In systems whose requirements are derived from legislation, there is usually imprecision or overlap in the understanding of the laws involved. So what you usually do is define some possible cases and specify them using input data as an example and exemplifying the output. Either way, the developer will need to have a minimal understanding of the legislation to verify if what he is implementing makes sense.

For general business rules, I see many analysts simply write a text document with the "algorithm" in descriptive mode. This works, but the developer needs to transform this understanding into code, so he has to master the technology.

Some technical analysts go so far as to specify implementation details. This is good if the developers are beginners, but on the other hand "tie" the implementation and usually does not generate an optimal solution.

A principle drawn from all the above observations, from much reading and practical experience is that developers need to be technically enabled to write quality code and at the same time understand well the object of what they are doing.

Another principle is that each area of knowledge should already possess its proper means of specification.

In practice, a good specification nay ensures a correct implementation, especially because most bugs are not intentional. Documentation never will replace good professionals. In fact, nothing replaces good IT professionals working side by side with business people understanding what they do.