Good PLC Program Documentation

[franji1]

Good software development standards apply in C++ Windows Programming along with PLC Programming.

Checklist of Good Commenting Techniques

General

• Can someone pick up the code and immediately start to understand it?
• Do comments explain the code’s intent or summarize what the code does, rather than just repeating the code?
• Are comments up to date?
• Are comments clear and correct?
• Does the commenting style allow comments to be easily modified?


Statements and Paragraphs

• Do comments focus on why rather than how?
• Do comments prepare the reader for the code to follow?
• Does every comment count? Have redundant, extraneous, and self-indulgent comments been removed or improved?
• Are surprises documented?
• Have abbreviations been avoided?
• Is the distinction between major and minor comments clear?
• Is code that works around an error or undocumented feature commented?


Data Declarations (Designer Documentation Extra Info and/or Description fields are good for these)

• Are units on data declarations commented?
• Are the ranges of values on numeric data commented?
• Are coded meanings commented?
• Are limitations on input data commented?
• Are flags documented to the bit level?
• Are magic numbers replaced with named constants or variables rather than just documented? (Do-more supports Symbolic Constants)


This material is copied and/or adapted from the Code Complete 2 Website at cc2e.com.  This material is Copyright (c) 1993-2004 Steven C. McConnell. Permission is hereby given to copy, adapt, and distribute this material as long as this notice is included on all such materials and the materials are not sold, licensed, or otherwise distributed for commercial gain.

[Garyhlucas]

I had a young programmer working for me writing assembler to control a machine we were selling around 30 years ago. Every few days I'd sit down with him and ask him to explain some of the code to me. If he hesitated in his explanation I'd stop him programming and have him document instead. When he left after 4 years we had 500 pages at 80 lines per page of well documented code. He got hired away by Mcgraw Hill, and told me later that all that documenting turned out to be very valuable to him later.

[Controls Guy]

Nice idea for a thread, franj1.

Also very much appreciating that Do-More stores docs onboard.  Big advantage!   

[franji1]

The Symbolic Constant feature is quite powerful.

For example, if you utilize the Date/Time in your application, creating Symbolic Constants like
Jan 1
Feb 2
Mar 3
...

Sun 0
Mon 1
Tue 2
...

Then your relational contacts can look like

$Now.Month Jan
-----] = [-----

or

$Now.DayOfWeek Sun
-------] = [-------


Hardcoded Recipe indexes (e.g. 0 is Doritos, 1 is Tostitos, 2 is Fritos, etc.)

Anything that is an "enumeration" of something, then Symbolic Constants can make the native ladder logic more readable.