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.

12/17/2013


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.



Engineers' Choice Awards
The Engineers' Choice Awards highlight some of the best new control, instrumentation and automation products as chosen by Control Engineering subscribers. Vote now (if qualified)!
System Integrator Giants
The System Integrator Giants program lists the top 100 system integrators among companies listed in CFE Media's Global System Integrator Database.
System Integrator of the Year
Each year, a panel of Control Engineering and Plant Engineering editors and industry expert judges select the System Integrator of the Year Award winners in three categories.
How to Maximize Factory Automation Efficiency with Low Cost Machine Vision
This eGuide illustrates solutions, applications and benefits of machine vision systems.
Wireless Reliability in Harsh Environments
Learn how to increase device reliability in harsh environments and decrease unplanned system downtime.
Human Factors and the Impact on Plant Safety
This eGuide contains a series of articles and videos that considers theoretical and practical; immediate needs and a look into the future.
May 2018
Salary and Career Survey, IT and OT convergence, robotic standards and safety, secure circuit protection
April 2018
Cybersecurity best practices, artificial intelligence, robotic additive manufacturing, embedded systems, IIoT integration, energy efficiency
March 2018
Digitalization integration, process sensors, edge computing, fog computing, condition monitoring, and motors
Edge Computing
This article collection contains several articles on how today's technologies heap benefits onto an edge-computing architecture such as faster computing, better networking, more memory, smarter analytics, cloud-based intelligence, and lower costs.
IIoT: Machines, Equipment, & Asset Management
Articles in this digital report highlight technologies that enable Industrial Internet of Things, IIoT-related products and strategies.
PLCs
Programmable logic controllers (PLCs) represent the logic (decision) part of the control loop of sense, decide, and actuate. Featured articles in this digital report compare PLCs and programmable automation controllers (PACs), industrial PCs, and robotic controllers.
SIDB

Find and connect with the most suitable service provider for your unique application. Start searching the Global System Integrator Database Now!

April 2018
ROVs, rigs, and the real time; wellsite valve manifolds; AI on a chip; analytics use for pipelines
February 2018
Focus on power systems, process safety, electrical and power systems, edge computing in the oil & gas industry
December 2017
Product of the Year winners, Pattern recognition, Engineering analytics, Revitalize older pump installations
John O. Ayuk, PE, CFSE, PMP, CAP
Automation Engineer; Wood Group
Doug Baker
System Integrator; Cross Integrated Systems Group
Jose S. Vasquez, Jr.
Jose S. Vasquez, Jr.
Fire & Life Safety Engineer; Technip USA Inc.
Data Centers: Impacts of Climate and Cooling Technology
This course focuses on climate analysis, appropriateness of cooling system selection, and combining cooling systems.
Safety First: Arc Flash 101
This course will help identify and reveal electrical hazards and identify the solutions to implementing and maintaining a safe work environment.
Critical Power: Hospital Electrical Systems
This course explains how maintaining power and communication systems through emergency power-generation systems is critical.
Engineers' Choice Awards
The Engineers' Choice Awards highlight some of the best new control, instrumentation and automation products as chosen by Control Engineering subscribers. Vote now (if qualified)!
System Integrator Giants
The System Integrator Giants program lists the top 100 system integrators among companies listed in CFE Media's Global System Integrator Database.
System Integrator of the Year
Each year, a panel of Control Engineering and Plant Engineering editors and industry expert judges select the System Integrator of the Year Award winners in three categories.
How to Maximize Factory Automation Efficiency with Low Cost Machine Vision
This eGuide illustrates solutions, applications and benefits of machine vision systems.
Wireless Reliability in Harsh Environments
Learn how to increase device reliability in harsh environments and decrease unplanned system downtime.
Human Factors and the Impact on Plant Safety
This eGuide contains a series of articles and videos that considers theoretical and practical; immediate needs and a look into the future.
May 2018
Salary and Career Survey, IT and OT convergence, robotic standards and safety, secure circuit protection
April 2018
Cybersecurity best practices, artificial intelligence, robotic additive manufacturing, embedded systems, IIoT integration, energy efficiency
March 2018
Digitalization integration, process sensors, edge computing, fog computing, condition monitoring, and motors
Edge Computing
This article collection contains several articles on how today's technologies heap benefits onto an edge-computing architecture such as faster computing, better networking, more memory, smarter analytics, cloud-based intelligence, and lower costs.
IIoT: Machines, Equipment, & Asset Management
Articles in this digital report highlight technologies that enable Industrial Internet of Things, IIoT-related products and strategies.
PLCs
Programmable logic controllers (PLCs) represent the logic (decision) part of the control loop of sense, decide, and actuate. Featured articles in this digital report compare PLCs and programmable automation controllers (PACs), industrial PCs, and robotic controllers.
SIDB

Find and connect with the most suitable service provider for your unique application. Start searching the Global System Integrator Database Now!

April 2018
ROVs, rigs, and the real time; wellsite valve manifolds; AI on a chip; analytics use for pipelines
February 2018
Focus on power systems, process safety, electrical and power systems, edge computing in the oil & gas industry
December 2017
Product of the Year winners, Pattern recognition, Engineering analytics, Revitalize older pump installations
John O. Ayuk, PE, CFSE, PMP, CAP
Automation Engineer; Wood Group
Doug Baker
System Integrator; Cross Integrated Systems Group
Jose S. Vasquez, Jr.
Jose S. Vasquez, Jr.
Fire & Life Safety Engineer; Technip USA Inc.
Data Centers: Impacts of Climate and Cooling Technology
This course focuses on climate analysis, appropriateness of cooling system selection, and combining cooling systems.
Safety First: Arc Flash 101
This course will help identify and reveal electrical hazards and identify the solutions to implementing and maintaining a safe work environment.
Critical Power: Hospital Electrical Systems
This course explains how maintaining power and communication systems through emergency power-generation systems is critical.
Engineers' Choice Awards
The Engineers' Choice Awards highlight some of the best new control, instrumentation and automation products as chosen by Control Engineering subscribers. Vote now (if qualified)!
System Integrator Giants
The System Integrator Giants program lists the top 100 system integrators among companies listed in CFE Media's Global System Integrator Database.
System Integrator of the Year
Each year, a panel of Control Engineering and Plant Engineering editors and industry expert judges select the System Integrator of the Year Award winners in three categories.
How to Maximize Factory Automation Efficiency with Low Cost Machine Vision
This eGuide illustrates solutions, applications and benefits of machine vision systems.
Wireless Reliability in Harsh Environments
Learn how to increase device reliability in harsh environments and decrease unplanned system downtime.
Human Factors and the Impact on Plant Safety
This eGuide contains a series of articles and videos that considers theoretical and practical; immediate needs and a look into the future.
May 2018
Salary and Career Survey, IT and OT convergence, robotic standards and safety, secure circuit protection
April 2018
Cybersecurity best practices, artificial intelligence, robotic additive manufacturing, embedded systems, IIoT integration, energy efficiency
March 2018
Digitalization integration, process sensors, edge computing, fog computing, condition monitoring, and motors
Edge Computing
This article collection contains several articles on how today's technologies heap benefits onto an edge-computing architecture such as faster computing, better networking, more memory, smarter analytics, cloud-based intelligence, and lower costs.
IIoT: Machines, Equipment, & Asset Management
Articles in this digital report highlight technologies that enable Industrial Internet of Things, IIoT-related products and strategies.
PLCs
Programmable logic controllers (PLCs) represent the logic (decision) part of the control loop of sense, decide, and actuate. Featured articles in this digital report compare PLCs and programmable automation controllers (PACs), industrial PCs, and robotic controllers.
SIDB

Find and connect with the most suitable service provider for your unique application. Start searching the Global System Integrator Database Now!

April 2018
ROVs, rigs, and the real time; wellsite valve manifolds; AI on a chip; analytics use for pipelines
February 2018
Focus on power systems, process safety, electrical and power systems, edge computing in the oil & gas industry
December 2017
Product of the Year winners, Pattern recognition, Engineering analytics, Revitalize older pump installations
John O. Ayuk, PE, CFSE, PMP, CAP
Automation Engineer; Wood Group
Doug Baker
System Integrator; Cross Integrated Systems Group
Jose S. Vasquez, Jr.
Jose S. Vasquez, Jr.
Fire & Life Safety Engineer; Technip USA Inc.
Data Centers: Impacts of Climate and Cooling Technology
This course focuses on climate analysis, appropriateness of cooling system selection, and combining cooling systems.
Safety First: Arc Flash 101
This course will help identify and reveal electrical hazards and identify the solutions to implementing and maintaining a safe work environment.
Critical Power: Hospital Electrical Systems
This course explains how maintaining power and communication systems through emergency power-generation systems is critical.
click me