Code Quality and Decomposition

I spend the past few weeks reviewing code in Lotus Notes applications. While the robustness of the platform amazed me, the code I saw didn't (short of that one form with 1932 fields and 212 @DBLookups).There seems to be a common lack of coding quality among corporate LotusScript developers.

I hear: "C'mon what is your problem? The code is working."

I reminds me of the guy who jumped from the 88 story building stating "So far everything is fine" when falling past the 10th floor. Unfortunately very often the person who writes the code (being a contractor) doesn't have to maintain it, so bad engineering kicks in.

When you write code you should make one base assumption: "The guy who will have to maintain your code is an armed maniac and has your address".

Sadly the statement "It is working" neglects the most basic principle of software engineering:

we don't write code for machine, we write code for humans to understand.

Machines don't "understand" code, they just execute it. Enough of the rant, what needs to be done, what makes good code?

In a nutshell: decomposition. Decomposition is a fancy word for breaking down tasks into smaller units until a unit solves exactly one problem. The recommended approach for this is top-down development.

The Stanford Computer Engineering class uses your morning routine as example. The big task is "Morning routine".

Morning routine can be broken down into: Get out of bed, morning hygiene, breakfast, get to work. These tasks can be further broken down, lets take breakfast as example (Stanford uses the morning hygiene, so you have 2 now): Prepare Breakfast, Eat Breakfast, Read Newspaper.

Prepare Breakfast can be broken down to: Kiss wife, make coffee, make eggs, get juice, make toast.

Make coffee can be broken down to: get water, get coffee powder, fill machine, boil coffee. Get coffee powder can be broken down into: get box with beans, fill grinder, grind, get grinded powder.And so on.

Whatever programming language you use (even in COBOL) you could just write down in natural language what you do and then implement the sub routine:

Sub Breakfast

    PrepareBreakfast
    EatBreakfast
    ReadNewsFeed

End Sub

Sub PrepareBreakfast

  Do until sheIsSmiling
        sheIsSmiling =  KissSWMBO
  End Do

  MakeCoffee 2
  MakeEggs 4
  MakeToast 2

End Sub

There are a number of tips (lifted from the Stanford lesson without asking) around decomposition:

• Break your program down until a routine solves just one problem. That one problem: HaveBreakfast then gets broken down into smaller tasks. This is a subject of heated discussion, when you reached that one problem. But you can for sure tell, that acquiring a collection of documents, looping through them and manipulate one document at a time are 3 problems.
• Methods are short. In the Stanford lecture a number between 1 and 15 lines was stated. I would say: a method (function, subroutine) needs to be readable on screen without scrolling (so your methods get shorter when you develop on a netbook)
• Methods have good names. If you read your program out aloud it should tell the story. function1 function2 doesn't cut it. The computer doesn't care, but keep in mind you write your code for other people to read and understand. (OK, nothing beats this COBOL statement: PERFORM makeMoney UNTIL rich [Fullstop])
• Methods have comments. What does the routine do? Any special considerations. What are the pre- or post- conditions. For LotusScript use LSDOC to generate documentation out of the comments.
• Decomposition is valid for procedural, functional and object oriented programming.

You want to know more?

• Take the free course
• read books about
• OO Design
• Software Engineering
• Code Complete
• Beautiful Code

As usual YMMV