Rules for good coding style
I started this with the idea of writing a blog about “Rules for good RPG coding style”, I was discussing this with an old friend and colleague yesterday. He moved away from the AS400 machine, just as it was being replaced with the old iSeries machine. He’s now spent nearly twenty years working in the Windows programming world and we had some fun comparing, mocking and arguing about our different styles of programing.
The misconceptions he had, were mainly because he left the IBM world back in the days of OPM programming style.
OPM vs ILE
OPM – Original Programming Model is the name that IBM uses to denote the old RPG3 and RPG400 versions of RPG where any given program was written and compiled as one executable object. This lead to large programs with multiple subroutines, often repeating code used in other OPM programs.
With the death of the AS/400 and the release of the IBM iSeries hardware, the new version of RPG had some ground shaking changes called ILE:
ILE – Integrated Language Environment is the name that IBM uses to denote the newer RPGLE versions of RPG where any given program is consider a *MODULE. We break logic down into separate compiled models and then create a *PGM which binds all these modules together. Any individual *MODULE can be bound into different *ILE programs
Obvious benefits of ILE are that we can make a change to any given module and then simply update the various programs that use to have that new logic immediately available within those programs.
And shhhhh – this is very very similar the the code functions that have been in the windows world for ever.
Good organization of any programs source code, using meaningful variable names will help readability, and using code comments will help the reader understand what the program is doing. This much is obvious.
After enjoying our programming style joust we came up with 5 qualities that we both focus on when writing code
5 rules for good code
- Source code must be easy to understand and maintain
- Small re-useable code blocks that do one job
- Clear common variable ‘naming standards’
- Source comments are good – but only if they describe functions not what a function is doing (ie: saying “read file” is useless but “read order header to find order date” is useful)
- indent code to make IF/DO loops easily readable
We couldn’t agree on MOD MARKS.
Mod Mark to comment every line that is changed
I used to leave a modification mark on every line of code I changed. This leads to huge blocks of code with my mod-mark (NJL01 for example) on every single line. The problem with this technique is that over time, as those sections of code are changed, enhanced or removed by other programmers, with their own mod-marks, the code can become unreadable.
Over zealous mod-marks can have the opposite effect of “making code readable”
Nowadays, I prefer to leave a description in the header of the program and then a comment block on or near the code I am changing, describing the change. Then I rely on my change management tool to show versions before or after my changes.
I’ve also adopted a technique which is a bit HTML’ish
I like to add a start of change comment <NJL01> and an end change </NJL01>
But, as always, I’m open to be convinced of a new/better/cleaner technique 🙂