Good vs. poor documentation: Don’t be ‘that guy’

A well organized and well documented system, complete with commentary within your code, can only help you and your fellow developers and programmers.


Over the years we have all had to modify, repair, debug, and otherwise live with someone else’s code. The platforms vary, but the challenges remain the same—the biggest of which is, “What in #@$! was this guy thinking?!” Looking at that single—sometimes painful and often confusing—question leaves us wondering how it happened in the first place.

More often than not, we find ourselves in this perplexing situation because the documentation has become separated from the program. This can happen for various reasons:

- The equipment has changed hands several times, misplacing information
- Someone saw this as an opportunity to insure continued employment by being the ‘go to’ guy
- The dog ate it
- It was never developed because the intent was “self-evident to anyone who knows what they’re doing”
- The information was intentionally stripped.

These are just a few of the many reasons. We as developers and programmers can’t do much about the first two; this is simply a fact of life and is typically caused by our end-user. Meanwhile, that pesky dog has been a haunting presence since grade school and will probably never die. But it is the last two reasons that are well within our control.

When we put a program or project together it is critical to truly complete the job. A big part of that complete job is a well organized, well documented, and maintainable system. The more tightly bound this information is with the actual code and configuration, the better. The more thought-out and organized the code, the better. It’s important to keep in mind that no matter what, you will probably NOT be the only person who will have to work with the code or configuration. There is also the issue of remembering what you meant as well. Believe it or not, the documentation and commentary starts before the first line of code is generated.

Code and configuration commentary does not have to be a literary masterpiece. You’re not being graded on grammar and spelling. The most important point is to simply leave the explanation of what was done and why. Make the in code commentary sections easily maintainable, this encourages others to follow your lead. Recent development environments aid in the documentation process by pulling that information forward through various construct use, provided the commentary is supplied from the beginning.

To those people who intentionally strip comments and don’t supply documentation, there’s a “special place” set aside for you. Unless the deliverable was only specified to be a compiled executable with no source code, there is no excuse. Somebody somewhere will have to deal with the mess that you leave behind. You’re only hope is that voodoo dolls don’t work.

In the end nothing anyone says or does can force you to realize the benefits of good documentation. We all appreciate well documented code and configurations. This is in the end a learned habit. There is only one real learning experience that will change your ways and that is digging around in a program and cursing the original developer, only to realize that ‘that guy’ was you!

Don’t be ‘that guy.’

This post was written by Jeff Monforton. Jeff is a Senior Engineer at MAVERICK Technologies, a leading automation solutions provider offering industrial automation, strategic manufacturing, and enterprise integration services for the process industries. MAVERICK delivers expertise and consulting in a wide variety of areas including industrial automation controls, distributed control systems, manufacturing execution systems, operational strategy, business process optimization and more.

Anonymous , 12/18/13 01:23 PM:

After 30+ years in the manufacturing industry I believe that poor documentation and commenting is one of the biggest contributor's to manufacturing and processing inefficiency.
The Top Plant program honors outstanding manufacturing facilities in North America. View the 2013 Top Plant.
The Product of the Year program recognizes products newly released in the manufacturing industries.
The Engineering Leaders Under 40 program identifies and gives recognition to young engineers who...
A cool solution: Collaboration, chemistry leads to foundry coat product development; See the 2015 Product of the Year Finalists
Raising the standard: What's new with NFPA 70E; A global view of manufacturing; Maintenance data; Fit bearings properly
Sister act: Building on their father's legacy, a new generation moves Bales Metal Surface Solutions forward; Meet the 2015 Engineering Leaders Under 40
Cyber security cost-efficient for industrial control systems; Extracting full value from operational data; Managing cyber security risks
Drilling for Big Data: Managing the flow of information; Big data drilldown series: Challenge and opportunity; OT to IT: Creating a circle of improvement; Industry loses best workers, again
Pipeline vulnerabilities? Securing hydrocarbon transit; Predictive analytics hit the mainstream; Dirty pipelines decrease flow, production—pig your line; Ensuring pipeline physical and cyber security
Upgrading secondary control systems; Keeping enclosures conditioned; Diagnostics increase equipment uptime; Mechatronics simplifies machine design
Designing positive-energy buildings; Ensuring power quality; Complying with NFPA 110; Minimizing arc flash hazards
Building high availability into industrial computers; Of key metrics and myth busting; The truth about five common VFD myths

Annual Salary Survey

After almost a decade of uncertainty, the confidence of plant floor managers is soaring. Even with a number of challenges and while implementing new technologies, there is a renewed sense of optimism among plant managers about their business and their future.

The respondents to the 2014 Plant Engineering Salary Survey come from throughout the U.S. and serve a variety of industries, but they are uniform in their optimism about manufacturing. This year’s survey found 79% consider manufacturing a secure career. That’s up from 75% in 2013 and significantly higher than the 63% figure when Plant Engineering first started asking that question a decade ago.

Read more: 2014 Salary Survey: Confidence rises amid the challenges

Maintenance and reliability tips and best practices from the maintenance and reliability coaches at Allied Reliability Group.
The One Voice for Manufacturing blog reports on federal public policy issues impacting the manufacturing sector. One Voice is a joint effort by the National Tooling and Machining...
The Society for Maintenance and Reliability Professionals an organization devoted...
Join this ongoing discussion of machine guarding topics, including solutions assessments, regulatory compliance, gap analysis...
IMS Research, recently acquired by IHS Inc., is a leading independent supplier of market research and consultancy to the global electronics industry.
Maintenance is not optional in manufacturing. It’s a profit center, driving productivity and uptime while reducing overall repair costs.
The Lachance on CMMS blog is about current maintenance topics. Blogger Paul Lachance is president and chief technology officer for Smartware Group.