2E - Development Standards (General Coding Considerations)

My regular readers will be aware that I have begun adding articles related to 2E (Synon) development. See links on Defensive programming and Programming for performance.

Future chapters planned for the coming weeks include:-

Parameters
Action Diagramming & Action Diagram Contexts
Messages and Message Handling
Subroutines
Wrapping, Relations and Function Options

DBA Best Practices

Function Type Best Practices

Gotcha's Guide

Suggested Naming Conventions

+ Much more.

When I have finally worked out how to use the Wiki. I will consolidated all my 2e postings and update.

I welcome all comments regarding these standards and guides and will endeavour to update the blog postings with your additional feedback and comments. At this stage I would also like to publicly thank Darryl Millington, Ray Weekes, Kim Motteram, Rene Belien, Rudy Moser and Mark Schroder for providing materials for review. As well as my now ex colleagues Kay, Kate, Nilesh and Sumit for their input and validation.

Today's theme is general programming considerations.

Functions should be as readable as possible. Try to fit the whole action diagram onto a single page by hiding case blocks and/or using sequences. Give these constructs meaningful names. Code should be easy to follow, where it is not intuitive add sufficient comments.

Always group and tidy up your code. Add comments where functionality is not obvious and always add comments for actions, *COMPUTE built in function, iterations, case blocks and sequence blocks.

Be careful of adding sequence blocks for tidying code. Ensure that there are no usages of the *QUIT built in function that can be negated by nesting into a sequence block. Remember the *QUIT only exists the sequence it is in.

Remove commented out code. Commented out code should only be used to temporarily change code and for assisting with debugging. Once changes are considered permanent all commented out code should be removed. This helps with both action diagram readability and impact analysis.

Keep ‘parameter passing’ to a minimum. Functions are more reusable if they do any required retrieving of database values internally. However, consider performance issues of this for large applications or performance critical programs where the opposite will be more practical.

Define all User Programs to the model. (CL, COBOL, RPG or RPG ILE). These should be declared in the model. If there is no obvious file to associate them with, add them to a generic scoping file. There must be a special case to write in native COBOL, RPG or RPGLE and this should be given careful consideration and were practical discuss with your peers.

Modularise. When copying large chunks of code from one function to another, put the code into an EXCINTFUN or EXCEXTFUN function. This avoids ending up with the same code in lots of programs.

Centralise common business calculations. Common calculations such as GST, Interest, withholding tax (finance examples) should be defined in one function and reused.

Ensure correct setting of critical function options.

Close Down Program Flag. Set to 'N' if program is called repeatedly in a loop or a processing function like a RTVOBJ. This means that any files that are open will remain open, thus improving the performance of the function dramatically. Set to 'Y' otherwise if the program is typicially a top level programs.

Reclaim Resource flag. Set to 'Y' on W/W functions, e.g. W/W Clients or other top level, W/W Funding Account. Otherwise lots of files stay open all day and will eventually consume more system resources than the system requires.

Best Practice - Updating balances or other value fields. Never use a RTVOBJ to get values from a record on the file, calculate the new values and then do a CHGOBJ with new values. You must pass the values to be added as separate fields into the CHGOBJ and then add them on to the DB1.fields inside the CHGOBJ before update. This is to take care of the automatic AS400 locking functionality on the update index as well as ensuring that you are incrementing the latest value available.

Use appropriately named fields. When using a field as a work field or screen/report field (i.e. A user field), create one with a meaningful name if one does not exist already. Using a field just because it has the correct domain attributes can be very confusing for people maintaining the function after you. Avoid generic named fields like Count 1 or Text (25).

Consider correct use of action diagram contructs. The use of *OTHERWISE blocks for grouping code is slightly misleading. Always create a sequence block. Note with RPG4 the limits for the number of subroutines is unlikely to be reached. The action diagram colouring of Pink, Green, White and Blue has inherent meaning and this fundamental principle in your action diagramming should remain. Put simply, Pink equates to a Decision, Green an Action, White as a collection of statements and Blue as an iteration.

The *OTHERWISE is still valid if deliberately trying to force a compilation error.

Avoid use of Derive Fields in screen designs. Not all of the CALC function points work correctly and this also hinders your ability to externalise code for thin client development.

Thanks for reading.
Lee.