Ecrire un pseudo-code! ça améliore la qualité du développement...

Source:
http://gnstudio.wordpress.com/2011/02/13/pseudocode-and-agile-modeling/

Introduction
The purpose of this article is not to be an omni-comprehensive guide about pseudocode but a starting point for a discussion about possible usages and the benefit we are experiencing from the usage of pseudocode during our development process.
We are so enthusiast about pseudocode that we are developing an Eclipse plug-in to create effective pseudocode models, more information about the plugin (currently in beta) are available here http://agile.gnstudio.com/apdt.

What is pseudocode
Pseudocode is a compact and informal description of an algorithm or of an entire program and can be used also to improve the communication between technical guys and not technical guys, and between experienced and less experienced programmers.
Pseudocode usually omits details that are not essential for human understanding and doesn’t use any language specific syntax; the intent is to make easier exchanging ideas about the key principles of an algorithm or, just in case you are not working in a team, to figure out quickly what have to be implemented by the algorithm.
Several books and courses use pseudocode as way to teach programming language to students. Often students start to write down code as they receive a problem statement but we believe that the right approach (not only for students but also in the real life) is to “design first” and that pseudocode should be one amazing way to design the code due to its simplicity.
Pseudocode should not contain too many details and has to be written with very informal English because otherwise people could have the feeling to be learning a new programming language and start thinking that it’s a time waster.
A snippet of pseudocode may look like this

INIT the hours worked by an employee
READ maximum allowed hours FROM web service
IF workedHours > maxAllowed THEN
SHOW overtime message
ELSE
SHOW regular time message
ENDIF

As you can see it is very simple to read and understand also for not technical guys and the logic is absolutely clear for everyone.

Best practices
While understanding pseudocode is usually not difficult, writing it can be a challenge especially because it’s very easy to be too much detailed or too much related to a programming language.
Pseudocode strikes a precarious balance between the understandability and informality of English and the precision of code. If we write an algorithm in English, the description may be at so high a level that it is difficult to analyze the algorithm and to transform it into code. If instead we write the algorithm in code, we have invested a lot of time in determining the details of an algorithm we may not choose to implement or that doesn’t fit completely the requirements of the software we are working on.
The goal of writing pseudocode then is to provide a high-level description of an algorithm which facilitates analysis, eventual coding and the production of the documentation. The boundaries outlined by the words “high-level” depend on the audience, algorithms written for different audiences have to be written with a different level of details.
For this reason we strongly encourage to ignore unnecessary details but to keep always the pseudocode logically grouped and indented in order to improve readability and to focus the attention on the logic of an algorithm.
In order to keep alive the attention of your readers avoid to belabor the obvious, it’s not critical to specify the data type of a variable or to set up the counter to use in a loop when you are writing some pseudo code.
An easy way to keep short and concise your algorithms is the usage of the English words that are standard in most of the programming language: if, then, else, etc.
Another good habit is to consider the context and to avoid redundancies; if an algorithm deals with quicksort is not useful at all to write something like “use quicksort to sort the values”, it’s too much at high level but, if your model already defined some good quicksort algorithms, it’s not useful to repeat again the logic.
It’s very hard to keep the pseudocode easy to read because actually it’s text. In order to improve readability a tree can be used, in this way the indentation will help you to group logically the pseudocode and to avoid creating confusion and misunderstanding.

Pseudocode as an iterative modeling
The construction of a Class or of an algorithm usually it’s an iterative process that start with the definition of the responsibilities of a Class and that move on with the production of a general design and the enumeration of specific routines within the Class.
When the routines are defined, discussed and refined usually the process move on the next steps that is the definition of the details of each routine.
It’s very important to write down pseudocode at a level of intent describing the meaning of the approach rather then writing down how the approach will be implemented in the target language. In this way building code around it will be nearly automatic and the pseudocode will turn quickly into programming language comments.
Pseudocode supports the idea of iterative refinement. You start with a high-level design, refine the design to pseudocode, and then refine the pseudocode to source code. This successive refinement in small steps allows you to check your design as you drive it to lower levels of detail. The result is that you catch high-level errors at the highest level, mid-level errors at the middle level, and low-level errors at the lowest level before any of them becomes a problem or contaminates work at more detailed levels.
The continuous iteration over this process is a great way to do iterative modeling. Each step involves several sub steps, let’s focus our attention on the definition of the routine’s details using pseudocode.
The first step to perform is to define clearly the problem a routine will solve with enough details to allow the definition of the steps involved into the routine. The information you may need are the inputs needed by the routine, the output it will produce and what the routine will hide or even better will do behind the scene.
After this information is clear you can start to define a name of the routine. Naming a routine might seems a trivial task but it isn’t, remember that meaningful and not too long names are one of the building blocks of good quality code.
Before writing down the details of the routine we strongly encourage to make a small research in the code base of the organization in order to avoid re-defining the obvious (i.e. something that is already designed and it’s already working). If you get something from the code base it’s enough to refer to another routine and keep your pseudocode shorter.
Often a routine can generate an error, think to all the things that can go wrong in the routine (e.g. bad input values, invalid returned values, etc.) and define a strategy to handle gracefully the errors.
After completing the preceding steps you already done with your design because you should have a diagram like the following one but it’s a good habit to go deeper in the modeling on core components.

Especially with core components it’s very hard to summarize in few lines what a routine is supposed to do, for this reason you can go deeper writing down the logic of the routine, how data are retrieved and manipulated, how the app will react to the user input, etc.
When you believe a pseudocode snippet is completed we believe it’s the time to ask to someone else to read it. You don’t need a technical leader or an architect, ask to read it to any of the stakeholders involved in the project and you will be surprised how it’s easy to catch high level or logical errors before starting to write down the code.
The general idea is to iterate the routine until the pseudocode statements are simple enough that you can use each of them as comment in the code you will write. Keeping updated the pseudocode and refining it continuously seems to be a waste of time but it helps a lot; this is one of the main reason why we started to work on APDT.

Pro and cons
The introduction of pseudocode in our organization is improving our production process because it impacts the following fields

• Reviews
• Documentation
• Liability to changes

Pseudocode makes reviews easier. We are used to do code review and often it’s hard for the reviewer to jump in the logic of a group of Classes and state if the code fits the overall architecture or not. The usage of pseudocode let us be able to move split the review in two phases, one happens at the beginning of the production process when people can discuss and review the logic of the algorithm, the second one happens when code is done but at this point logical issues have been already addressed and the review can be focused on speed, efficiency, etc.
Through pseudocode we are getting a documentation that it’s really easy to maintain rather than large diagrams and even more we use it as comments in the code in order to produce quickly a quite well refined JavaDoc for each Class we write down.
A few lines of pseudocode are easier to change than a page of code so your program can be changed easily during the modeling phase and can be discussed during production in a very fast way so that architects can provide their advice in time.
There are also some cons in the usage of pseudocode, for instance developers sometimes waste time on it because they add to much details and tend to write code. We strongly encourage keeping the pseudocode at a high level (until a good reason to go deeper came out) avoiding putting in place coding details that can be understandable only by developers.
Another issue we are expecting is that it’s very hard to test the logic of complex routines defined through pseudocode and for this reason we are working on a component for APDT to help us test the logic.
The biggest issue we are getting is that a high-level language limits the programmer’s flexibility. Additionally, the programmer can fail to distinguish between the analyst’s coding technique and the analyst’s design, and the result may bring to the rejection of a perfectly good design based on inappropriate criteria.

Pseudocode Syntax
As the name itself suggests the pseudocode generally does not follow any specific syntax rule and details like opening a file, initialize a counter are explicitly coded but language dependent details are ignored.
There are several document on the web that define different syntaxes to use writing down pseudocode (also our organization defined here http://agile.gnstudio.com/apdt/wiki/Pseudo_code_syntax the basic rules) but again the overall concept is to describe a routine in a form that a developer can easily translate into code and analysts can quickly check. One of the most complete syntax definition has been made by Stuart Garner, he created a library for NoteTab in order to write down pseudocode.
Our recommendation is to keep it clear, logically grouped and short as much as possible (until understandable) so that you can really improve the writing code process of your organization.

Conclusions
The usage of pseudocode is usually more related to students but we strongly believe that it is a way to improve the quality of code in all the organization. The major field of appliance is distributed teams because communication can be a challenge, in this scenario a simple and easy exchangeable file that shows up the routines to work is more valuable that hours of online meetings.