Defensive Programming with PowerBuilder - EMEC - Part I

[Former Member]

Introduction

EMEC stand for Easy to Maintain and Effective Code.

This is another concept related to Defensive Programing in general but PowerBuilder makes no exceptions.

What is an "Easy to maintain code" ?

Easy to maintain code is a code that is Easy to read and that its structure indicate its intrasect logic. It should also be easy to adapt it rapidly.

The goal here is to produce a code that anyone can follows easily without being a Geek or a specialist in the domain concerned.

Use the right vocabulary

To achieve this, it is necessary to design the solution based on the concerned Domain terms and practices.

The first evidence, will be to name variable using the business domain's vocabulary along with a reasonable but strong naming convention.

This will allow to quickly point out Domain's concept data type and complexity.

Do not hesitate to create special datatype through structure & custom classes with well named members.

Use Smart comments

Add comments only when the code is not explicit by itselfs either because the concept is complex and/or because the implementation needed some optimization for performance purposes, for example.

Do not forget that comments should explain what does not appears only by reading the code. Explain what you want to do, not how you want to do it because it is exactly what does the code itself, no ?

Do not hesitate to paraphrase some Business Domain rules that applied to the concerned code, indicates the source of this information (Who ~fullname & When).

This will help successive programmers to easily find the right persons to contact in case of questions.

Consider the code + comments as the only valuable and really maintainable documentation

Who really has the time during their mission normal working hours to write and maintain a good and up to date external paper and/or electronic documentation nowaday ? Nobody. So keep focused to produce good code and up to date comments directly when needed, and do not do Procrastination !!!

Use source control & versioning solutions to keep code and comment up to date

Even if you are working alone, this will really help you to keep a trace of the old versions of the code and comments, and to avoid to skip elementary information that you could have scrapped inadvertently when trying to summarize too big comments sections.

Tag your modifications

Until your code has reached a sufficient state of robustness and maturity, I advise you to Tag any code changes with your acronym and a change reference (like CR from source control & versioning solutions) along with a short description of the reason. This will help you to follow up who has worked on certains portions of the code and why. Once the code is stable for a sufficient amount of time, organize a code review session to clean up these tags leaving the most pertinent comments. This will leave a more easy to read and aired code for the followers, while the entire code history is still available in the source control solution used, if needed.

Avoid Complexity as hell

Try to split complex functionality into smaller business objects. Use versatile techniques to achieve this (see previous blog to see how)

Keep Script as short as possible, code that is longer than maximum two pages, should be shortened by calling dedicated methods.

Preferably, method should do only one thing illustrated by its name and interface. User Verb/Noun template to name method.

Do not use Gaz Factory when it is not needed, go straight to the simplest code to understand instead to search directly better performance or more "Elegant" solution. This could come later, once your code has taken sufficient maturity and robustness. Off course, do not rebuild the wheel, if you have a well known template or component available, use it. But never forget, "the best is the enemy of the good", so do not optimize running code unless express and legitimate  request has been made by the end-users and/or customer !

Use simple code template structure

Use always the same sections based template, the most used is :

- Code Header

- Variable declaration,

- Parameters validation,

- Core treatment,

- Garbage collection

So stick on it.

Code Header

A good code header to be complete, should contains:

- Name and interface of the script (methods, events)

- A complete description of every parameters with their possibles values

- The purpose of the code and its usage in general

- Version History

Use third parties tools like SmartPaste or PBPaste (my favorite)  to help you to produce good header of code.

Variable declaration section - One line/One Variable sorted AZ

Avoid to declare multiple variables of the same type on the same line, but prefers to use one line per variable.

This will greatly enhance readability and maintainability :

- Renaming variable, Changing variable type, unused variables cleanup will be easier by avoiding to have to repaginate manually the entire variable sections.

Once changes are terminated, use a tool like NotePad++ to sort them alphabetically (data type + name), this will allow you to find them easily in the future.

Use method overloading technique to enhance the ease of use

Do not hesitate to overload methods to simulate optional parameters. This will make the usage of your classes more intuitive, and the code will be more readable. Ideally, overloading methods should invoke the base, real and concrete method with the most complete prototype in order to centralize the logic in only method, while the other simply passed default values for optionals parameters.

Use Symbolic Constants for discrete Parameter values

This will enhance code readability while encapsulating the real value in their definition location, making easier any future change in only one location.

Reusable Symbolic Constants should be auto instantiated custom classes

This will greatly enhance to portability, reusability and maintainability of the constants. Use a one character public instance variable like # or _ to easily access it.

This cloture the first part of this article by providing the most common used techniques to produce "Easy to Maintain" PowerBuilder Code.

In the second part of the article we will focus on how to produce "Effective Code".