Cobol Promo Original Promo

COBOL, Contracts, and Clarification

Feb. 24, 2020
Editor Bill Wong offers his take on COBOL, Ada contracts, and documentation considerations, and the common thread that ties them together.

Rodney Dangerfield’s catchphrase is “I don’t get no respect!”

That could easily be applied to the COBOL (Common Business-Orientated Language) programming language. COBOL may not be at the top of programmer popularity lists that now include the likes of Rust and Python, but COBOL code continues to run on many systems—and not just mainframes that grew out of the venerable IBM 360.

So why am I talking about a programming language that’s definitely not in the toolbox for most embedded developers? Well, there are a number of reasons. is a site I often read, and I recently saw Many Businesses Still Love COBOL. It highlights the article “COBOL stays top of mind for businesses in 2020 on techradar.

One other thing to add to the mix is my background with respect to COBOL. I’ve been a programmer for over 50 years and one of the first large programs I worked on was a COBOL compiler, written in HP BASIC. That does need a little explanation. The Hewlett-Packard (HP) 2000 minicomputer timesharing systems I had access to only exposed BASIC. FORTRAN and COBOL were popular at that point and used for “real programming.”

The BASIC-based COBOL development system was designed for teaching purposes. However, it actually provided a faster turnaround than generating applications using punch cards and waiting for them to be run on the IBM system that was also in the computer room. I eventually wrote and sold a similar system for FORTRAN development.

I didn’t do a whole lot of COBOL programming later in life, but had a pretty good handle on COBOL. It had its advantages especially when it came to handling numbers and text. It’s still easier to do many operations in COBOL than in other programming languages, including the Java, Python, and C/C++. There are probably more things that it doesn’t do as well when compared to other programming languages, but this often applies to chores that COBOL wasn’t designed to handle.

COBOL Commentary

But back to the comment stream in and the survey results from the related article. It notes that COBOL remains strong and even more lines of code are being generated. That doesn’t really surprise me, though. COBOL remains a good programming platform and the language has progressed over the years. Micro Focus remains one of the driving companies behind COBOL.

As someone who has played with both the original COBOL and the current version, it’s like night and day. Object-oriented support has been added and IDE support for the likes of Eclipse and Visual Studio put development on par with any other programming language out there.

But I digress again. Now about the comments in on the original article and survey results. As usual, everyone likes to add a comment, but few read the actual articles or have any frame of reference about COBOL. One thing that does crop up are comments about legacy code and the lack of documentation for maintenance. This is a valid complaint and really the focus of this article (yes, I know we’re already a page into the article; the original title of this article was going to be “COBOL, Contracts, and Documentation,” but I like the alliteration).

The problem with the complaint is that it can be made about programs written decades ago as well as ones written last week. We have many more tools like PHPDoc, JavaDoc, and Doxygen that turn inline comments into web pages that can be browsed by programmers. I currently do a bit of Drupal programming—it has an impressive site and programming support system that manages documentation as well as source code.

Though modular programming and reuse is useful, it only works if there’s good documentation. Way back when, even addition of inline comments wasn’t done because the compilers had to read all of those comments, and that was slooooowwwwww. Ok, it wasn’t quite that bad, but it was an excuse to minimize the amount and detail of comments. External documentation would be the norm for large projects, but keeping it in sync with the code was a major hassle. It’s also why a lot of the “legacy” COBOL code lacks accurate documentation.

Taking advantage of the inline documentation generation support has definitely been a step forward and it can easily double the number of lines within the source code. I would put that as a plus, though, because I even need that information when looking at code that I wrote months or years ago. Of course, all of this only helps if you take advantage of it, and, no, your code isn’t self-documenting—or can it be?

Ada Contracts

Here’s another of my pet topics: contract support in Ada.

One problem with inline documentation is that it often describes requirements for functional parameters and what type of actions might be performed. It may even cover what type and the state of data that’s returned or modified for later use. Unfortunately, it describes this in a text comment and has no effect on what the code or compiler is doing. In a sense, the comments are a contract whereby a programmer has promised that the code will operate in the stated fashion. The problem is that the code and comments can be as out of sync as the external documentation mentioned earlier.

Ada contracts are part of the “source code,” although they don’t necessarily generate “object code.” Thus, they don’t make the application larger or slower due to additional code.

SPARK, a subset of Ada, uses contracts to allow a program to be provable. I won’t get into the details, but essentially contracts are pre and post conditions for parameters and the result of a function or procedure. These can limit the values and relationships of the incoming data and indicate how state changes.

Contracts allow the compiler to do the kind of checking that would normally be done by a code review via programmers involved with the system. Having the compiler do this work simplifies the programmer’s job when it comes reusing code at the cost of defining what’s actually done by the code. This becomes very important as systems have grown more modular and dependent on libraries and runtimes provided by third parties. Questions always arise, though, such as “How good is that code?” “Does it do what the documentation says?” “Is it well tested?” And so on.

Ada contracts can make sure that the code using a library will work withthat library even when changes are made on either side. That’s because the contracts are verifiedi.e., violations are detectedeither through static analysis if the code is in SPARK, or with run-time checks for full Ada.

I mentioned how inline documentation could often exceed the amount of source code it’s describing. The same holds true for Ada contracts. Often these definitions are short and simple, but the complexity of a contract is application-specific.

Any programming language has some form of contract built into the definition. For example, languages that perform static type checking will alert a developer of a mismatch when a value is assigned to a variable. The big question is how much a particular language and compiler allow these contracts to be extended as well as how they’re enforced.

Ada contracts are often used in safety- and security-critical applications. The problem that most commenters will have is that they assume such contracts are only needed in these cases. I contend that they need to be used for any application and that the benefits are significant.

If you want to check out contracts and SPARK, wander over to Even if you don’t wind up learning or using Ada or SPARK, it will provide insights into what route you might go in other programming languages—even if it’s simply doing more in the inline comments that may or may not wind up in some documentation.

If you don’t use Ada and contracts, just the use of inline comment documentation is a move in the right direction. I wish some of this inline documentation did some minimal check, even if it was to match the arguments in the actual code. If you really want to see something bizarre, then check out the PSR-4 standard for PHP that handles autoloading of classes.

So, to wrap up, COBOL doesn’t have the cachet of functional programming languages like Haskell (yes, I have written a few programs in it) or Python (a popular language used with many of the machine-learning frameworks), but it remains a solid platform that many businesses continue to utilize and even update. COBOL has its place, and there are COBOL programmers out there doing good work and not nearing retirement. I haven’t found an inline-comment document generation system for COBOL, but would be interested in seeing one if it exists.

Here’s hoping that the next set of libraries I have to use offer decent and accurate documentation as well as real contracts.


To join the conversation, and become an exclusive member of Electronic Design, create an account today!