Style Guide

Writing Style

Chicago/APA/MLA - generally using a comma between 3 or more items separated in a list. One space after period/!/? ending sentences. Complete sentence in parentheses - period after closing parenthsis. Titles/subtitles/section titles - On 4/28/2026, SLM stated we should have initial caps in [these sections]. Had been inconsistent previously.

Class implementation standards

Names

Class names shall

  1. be entirely lowercase;
  2. begin with an alphabetic character;
  3. be composed use only the letters a-z and underscore character; and
  4. not use abbreviations.
  • Module implementation standards
  • Property implementation standards

Dev:module

Module implementation standards

Names

Modules names shall

  1. be entirely lowercase;
  2. begin with an alphabetic character;
  3. be composed using only the letters a-z and underscore character; and
  4. not use abbreviations.
  • Class implementation standards
  • Property implementation standards

Dev: Troubleshooting

Developer guide to adding troubleshooting messages

Online troubleshooting documentation is generated automatically from source code comments entered immediately after the code that generates the message in question. For example, the user receives the message 

FATAL: the GLPATH environment variable is not set

and must find out how to fix the problem. The message was generated from a line of code 

output_fatal("the GLPATH environment variable is not set");

which must be documented. To document the troubleshooting information, you must add a C-style comment on the next line

output_fatal("the GLPATH environment variable is not set");
/* TROUBLESHOOT
   GridLAB-D™ requires that GLPATH be set before the system
   starts.  Make sure the environment variable is set
   and try again.
 */

No exception is made for line continuations, therefore the code 

output_fatal("the GLPATH environment variable '%s' contains a folder that does not exist",
   getenv("GLPATH"));

can only be documented either as 

output_fatal("the GLPATH environment variable '%s' contains a folder that does not exist", getenv("GLPATH"));
/* TROUBLESHOOT
   GridLAB-D™ requires that GLPATH environment variable refer to
   folders that exist.  Make sure the environment variable is set
   correctly and/or all the folders are accessible and try again.
 */

(which is preferred) or as 

output_fatal("the GLPATH environment variable '%s' contains a folder that does not exist", 
/* TROUBLESHOOT
   GridLAB-D™ requires that GLPATH environment variable refer to
   folders that exist.  Make sure the environment variable is set
   correctly and/or all the folders are accessible and try again.
 */
   getenv("GLPATH"));

if the argument list is particularly long

Processing script

The troubleshooting guide is generated automatically by the nightly build process. The processing script source code is in utilities/troubleshooting.awk and generates an HTML file that should be placed in the root document of the www.gridlabd.org web site. There is a CSS stylesheet that also needs to be copied to the root document that is placed in the same source folder.

The command generate the HTML troubleshooting guide is 

host% **(cd trunk; ./utilities/troubleshooting.awk */*.{c,cpp} ) > $HTML/troubleshooting.html**
host% **(cd trunk; cp utilities/troubleshooting.css $HTML)**

Bulleted Lists

Generally initial caps and end each line with a period, unless lists are one or two words per line, then no period after line entry.