Good Programming Techniques

Introduction

What is an error? We could say that an error is a failure that is included in a program. It ruins the product and affects the client.

Let's examine it from another perspective. When we develop software we try to provide certain functionality to the user, if this functionality is not provided, the software is said to have errors.

The errors, we speak of, are quantifiable (detectables) to the user, and thus take us to the concept of external quality of the software.

Nevertheless, we still haven’t justified the purpose of this article: what is the reason for writing quality code? The reason is simple: the external look & feel of the software has a direct relationship to its internal quality, that is to say with its structure and design.

We all want to build correct, robust, expandable and reusable software. We should be conscious that the best way to achieve it is in fact to practice quality programming.

There are a great many other reasons why one should apply good coding techniques to software design. As developers we cannot forget that the code source is maintained and reused, thus we should take care of our programming to facilitate these tasks.

The aim of this article is to present in a simple, informal way to write good code. In addition, some particular techniques, as well as other general ones, will be presented in order to show good coding skills. Even if the reader disagrees with some of this advise, I expect to make the reader think about it, which undoubtedly will bring quantifiable benefits to your developement.

1. - Nomenclature

Good code is constituted by identifiers of variables, functions, procedures and classes. The selection of the names/identifiers is very important since they normalize the code, and make it easy to understand the real purpose of the code.

It is very important to use a very defined nomenclature in our code, since it increases its legibility, while making it vastly simpler to work in a team environment or to supervise employees. Keep in mind not to go overboard and specify rules for absolutely everything, because it will create more problems than it solves.

The most broadly used nomenclature is the 'Hungarian Notation', with numerous defenders and detractors, each one very armed with tons of arguments. Whether we like this nomeclature or not, it basically states that it is much more important to add information to the names of the identifiers than to be able to read the code aloud.

One of the central ideas in this notation is the use of prefixes that include information about the type of the identifiers. This proposal has certain disadvantages with regard to its usage in modern IDEs, mainly due to the existence of tools that inform us, as we type, about the different methods, attributes, variables, etc... available in that particular context.

However, you can use suffixes to specify certain information, for instance, related to the scope of the the variables: a topic that up to now has not been discussed that much.

A possible recommendation would be to use suffixes in the identifiers to indicate the valid scope of certain variables, using the following characters: 'C' for the class variables and 'G' for the objects or variables of global scope.

Public oCnnG As ADODB.Connection

Public Sub main()
    ' some code
    Sep oCnnG = New ADODB.Connection
    oCnnG.Open "DSN=XX;SERVER=XX", "XX", "XX"
    'some code
End Sub	

A small class example developed according to the norms described in this article would be:

CFile
Option Explicit
'Class Comments.
Dim bConsistC As Boolean
Dim sFilePathC As String

Public Sub Init(psFilePath As String)
    Debug.Assert (Dir(psFilePath, vbArchive) <> "")
    sFilePathC = psFilePath
    bConsistC = True
End Sub

Public Function sGetFileText() As String
On Error GoTo errCatch
    Debug.Assert (bConsistC = True)
    Dim iFile As Integer
    Dim sTempText As String

    iFile = FreeFile
    Open sFilePathC For Input As #iFile
    sTempText = Input$(LOF(iFile), #iFile)
    Close #iFile

    sGetFileText = sTempText
    Exit Function
errCatch:
    'Error code
End Function

2. – Ample use of Assertions and Validations.

One of the pillars of a solid programming is to be able to detect errors quickly during development so that we avoid having to deal with them once the product is shipped to the client.

The main mechanism to achieve this objective is the widespread and extensive use of validations in the code to detect invalid use of our methods, classes, functions and procedures. I call this ‘Classes and Blocks Shielding.'

I recommend, as a bare minimum, to validate the following entities in our functions and procedures: parameters, state of the object, contextual states, etc. The following piece of code is an abstract example of the above rule:

Class
Option Explicit
'Class Declaration and Coments.
'Class-Scope Declarations (remenber last character with 'C')

Public Sub SomeProcedure(Parameters_List)
On Error GoTo errCatch
    'Class state Validation (class variable and objects related with this class!!).
    Debug.Assert (bIamConsist() = True)
    Debug.Assert (oClass2C.State = adStateOpen)
    'Parameters validation, for example:
    Debug.Assert (bIsValidParam1(param1) = True)
    'If It is required Global state validation, for example:
    Debug.Assert (DatabaseConnectionG.State = adStateOpen)
    
    'some code
    Exit Sub
errCatch:
    'error catch.
End Sub

We could classify the validations as follows:

• Internal Validations. They are written to capture erroneous state during the development.
• Parameter Validations.
• Contextual Validations at Class level.
• Contextual Validations at Application level.
• External Validations. They are written to avoid erroneous state in the application that has been produced by interaction with external components (users, files, etc).

The only validations that will remain in the final product are the external validations (mainly those that deal with user interaction). The main purpose of internal validations is to aid us during the development cycle, and thus are preferably removed from the shipping product.

Quite often I am asked why I don't simply leave the internal validations? The answer is that they impose a high processing cost while providing zero benefit to the user. They help us enourmously, however, to develop quality code by indicating to us that a problem exists.

The topic of the validations is so important that if it is necessary that we should maintain additional information in our classes, modules, etc, to be able to make a stricter confirmation/validation of errors, than so be it.

3. – Architecture reuse.

The structure of most of the applications we create is very similar. We can observe that certain objects exist in almost all our programs. It is important to develop a clear and simple architecture in our application, aided by reusable pieces drawn from previous develpment projects, and design patterns.

For example, at a minimum we should be including in our common reusable framework certain types of support objects, such as registration and logging objects, error handling objects and possibly even some reporting support objects too. Typically we would want to declare some of these objects globally so that they can be used from anywhere within the application. Its also recommended that their interfaces are kept simple and uncluttered. Its very important that these objects are not tightly coupled to other pieces of the project - this makes them more reusable.

modMain
Public oLogG As CLogObject
Public oReportG As CReportObject
'.... BE CAREFUL, don't abuse global objects!!!!
Public Sub main()
    'some code
    'Initialize oLogG and oReportG
    'some code
End Sub

It is very important not to abuse global objects in our applications since this also can diminish the reusability of our classes (we make them much more interdependent). In any design one of the commandments is to develop modules, classes, components, etc highly decoupled with the rest. To that end, I repeat again, build these classes with a minimal interface, so that they are easily called from specific points of the rest of the code, and so that it is easy to 'plug-in' a different class instead of the first one.

4. - Some Specific Advice.

There are always a multitude of concepts we should keep in mind while building quality software. Here are some ideas that I have found important:

• Using error managers. Errors can happen anywhere, but it is evident that there are places in the code with a greater probability of generating errors. As a principle we should make wide use of error managers, but you are always left with choosing where to place error handlers and where to leave them out. We should not forget to always include error handlers in routines that make use of external resources outside of the application: interaction with databases, communication protocols, the file system, etc. This will help avoid the more famous "Runtime Errors". Not much is worse than your program hitting a "File Not Found" runtime error.
• Controlling the dependencies of each class. A common problem encountered when we want to reuse a class in another project, is that far too often we fail to recall the details of the necessary resources to make it work; that is to say what components it uses and what code needs to be written to set it up, etc. A certain amount of dependency is always necessary - but keeping track of how to set up and use the class is tedious. A simple mechanism to assist with this is simply including in the comment header of each class a line in which we specify all its dependences clearly (components that it uses, classes that are used, objects or global variables that it uses, etc).
• Validating object consistency. It is important that we make sure that a object is only used if it is in a consistent state. In VB it is not obligatory to use a constructor metaphor. Its not uncommon to see classes whose instantiation process takes several steps. Having a class variable that indicates whether or not the class is in a consistent state (that is to say if it has been initiated with all the data and references that it needs) is something that can save us many problems. In general I designate this variable 'bConsistC.'
• Creating well defined routines that adhere to a unity of function. Building functions that do only one thing (and do it well) makes for easier code reuse, assertion handling, not to mention coherency in your code
• Avoid semantic inequality. Code is basically structured in blocks of two types: functions and procedures. We should to attempt to code in such a way that in each code block, the abstractions that we manipulate are of a similar level.. This aids in the creation of clear and error-free code, besides producing code that is easier to understand.

5. – Some Other General Rules.

To conclude this not very orderly review on the practice of programming, I'll give some general recommendations on techniques that can help you develp quality code.

• Code Tracing. Its a great idea to get in the habit of stepping through your code right after you build each block. Its amazing the number of errors that can be detected early on, before they become serious problems, by this simple technique. In other words - don't wait till you have a bug to debug. Modern development environments generally make stepping through your code quite easy and painless - so don't avoid it.

• Practive Good Code Formatting. Anything that makes your code more readable is a good thing. You should make good use of white space, indenting, and structuring. Also don't make lines that exceed the width of the screen and force the reader to use the horizontal scroll bar.

  What is easier to read?

  1. - 
  Public Sub Procedure(Parameters_List)
  On Error GoTo errCatch
  Debug.Assert (ValidateSomething())
  If bSomeCondition = False Then
  DoSomething
  Else
  For Each object In colObjects
  If bSomeOtherCondition = False Then
  DoOtherThings
  End If
  Next
  End If
  Exit Sub
  errCatch:
  MsgBox Err.Description
  End Sub
  
  2. - 
  Public Sub Procedure(Parameters_List)
  On Error GoTo errCatch
      Debug.Assert (ValidateSomething())
      If bSomeCondition = False Then
          DoSomething
      Else
          For Each object In colObjects
              If bSomeOtherCondition = False Then
                  DoOtherThings
              End If
          Next
      End If
      Exit Sub
  errCatch:
      MsgBox Err.Description
  End Sub
  

• Use consistent and common user interfaces. It is important to build well-known environments for the user, and so we should not fear to copy the style of applications of common use. It is important to use visual structures that reflect the real structures that the user is managing. This allows the user to forget that an application exists between him and its data.
• Stay focused on the important things. Not all the options of a program have the same importance. So we should not forget to make sure that the really critical things works correctly first.
• Don't get hung up too much on writing quick code. Clarity in the code is much more important than squeezing that last ounce of performance out of something that is already relatively quick. Typically, speed depends on the architecture and technology used in an application and not so much on concrete details in our coding. If the code does not run in a loop try and avoid performance vs clarity tradeoffs.

Bibliography:

• Maguire, Steve. "Writing Solid Code". Microsoft Press (1993).
• Gamma, E., Helm, R., Johnson, R., Vlissides, J. "Design Patterns. Elements of Reusable Object-Oriented Software", Addison-Wesley, 1995.
• Meyer, Bertrand. "Object-Oriented Software Construction, 2nd Edition". Prentice Hall, 1999.
• Hamilton, J.P. "Fifty Ways to Improve Your Visual Basic Programs", http://vb.oreilly.com/news/vbshell2_0901.html.
• Díaz Toledano, Moisés Daniel. "Web Design Guidelines", http://www.geocities.com/moisesdaniel01/Articles/Princdisweb.html.

Moisés Daniel Díaz, Software Engineer.

Moisés Daniel is a Software Engineer that currently
works for the Andalusia Government. He is interested in
Object Oriented Analysis and Design, Pattern Oriented
Design, XML Technologies, Information Systems, Neural
Networks, and writing, reading, composing music,
photographs, and much more...
 
Moisés Daniel wants to develop small applications and
articles that can provide useful examples for developers
and help individuals create projects that before were
reserved only for teams.