Bookmark and Share
RSS

Recent Posts

Writing Unmaintainable Code

October 17, 2014

This week we thought wed introduce you to a great essay titled, "How to Write Unmaintainable Code." It will provide you with some weekend reading and should make you think hard about your own development style. Just so there is no doubt in your mind when you start reading, as the author says, It is amazing how many people dont realize it is tongue in cheek.”

When reading a piece like this it can be positively scary to realize just how often you are guilty of some the crimesmentioned. But in this blog post well stick (for the most part) to referencing the sections we found most amusing. For example, in the section on General Principleswe find:

To foil the maintenance programmer, you have to understand how he thinks. He has your giant program. He has no time to read it all, much less understand it. He wants to rapidly find the place to make his change, make it and get out and have no unexpected side effects from the change. He views your code through a toilet paper tube. He can only see a tiny piece of your program at a time. You want to make sure he can never get at the big picture from doing that. You want to make it as hard as possible for him to find the code he is looking for. But even more important, you want to make it as awkward as possible for him to safely ignore anything.

Sound like the average RPG monolith to you? It reminds us of far too many programs that we have had the pleasureof working on. In particular the part about safely ignoring anythingspeaks to the use of global variables that have no relationship to the rest of the logic in a subroutine. Even worse, the widespread use of global variables within subprocedures--at least theres an excuse with subroutines, you have no option.

By the way, while it may sound a like a lot of RPG programs we've seen, this essay was actually written primarily for Java programmers. It's surprising how many of the issues are the still the same.

The section on variable naming took Jon back to his early days in computing when program names such as WERT and ASDF were common for one-off programs and FRED a frequently used variable name. Why? Because they are all easy to type! We are both guilty of using single-character variable names for loop control, and this is perhaps the one point where we might argue with the author. As long as its use is confined to a very narrow scope, e.g. a simple For loop, we dont see a problem with naming an index i or x.

We dont think we have ever been guilty of Creative Miss-spellingbut it is possible because Jon is a transplanted Brit and therefore was indoctrinated at an early age into the mistaken belief that colouris the correct spelling.

The section on documentation is particularly enjoyable and sadly we have seen far too many examples of some of the sins mentioned. Jon has suffered many times from the skills of those who perfected the art of Lie in the commentsand Document How not Why.

Last but not least well just quote from the beginning of the section on Testing. It says it all:

Leaving bugs in your programs gives the maintenance programmer who comes along later something interesting to do. A well done bug should leave absolutely no clue as to when it was introduced or where. The laziest way to accomplish this is simply never to test your code.

Isnt job security wonderful!

We could go on but well leave you to read more for yourselves. You can read the complete essay (link not active) or alternatively you can work your way through specific topics by starting on this page. 

As we noted earlier, the original was intended for Java programmers and so some examples refer to features that we do not have available in RPG, but we think youll still get the point.

Wed love to hear what you think in the comments section. Perhaps you can even help us develop some RPG specific examples. Our favouritein that category would have to be the RPG program that made extensive use of conditioning indicators on the END statements of various loops. We had to write test code before we were certain what the impact of that was, not something that the RPG manual dealt with in detail! For that matter, the whole subject of RPG's numbered indicators in general would make for a big part of an RPG-specific version of this essay. How about seeing how many different things you can do in a program using the same indicator?

 

Posted October 17, 2014| Permalink

Post a Comment

Note: Comments are moderated and will not appear until approved

comments powered by Disqus