Note

This “source file” does not contain any useful, executable code. Instead, it exemplifies literate programming style.

style_guide.cpp - Style recommendations for CodeChat

Before covering style, the following shows the syntax used to embed reST in comments. The rules used to determine if a comment will be interpreted as reST are:

1. A comment must be placed on a line containing only comments or whitespace, but no code, preprocessor directives, etc.
2. One space must follow the opening comment delimier.

The following provide examples of the source code and its interpretation. The following source code...

// A line containing only a comment in interpred as reST.
  // Indented lines will be properly indented in the output, as well.
  /* Block comments may also be used.
     They may span multiple lines. */
     /* Block comment indents are
      * preserved, as well.
      */
  i = 0; // Comments with code are not
  j = 1; /* interpreted as reST. */

...becomes...

A line containing only a comment in interpred as reST.

Indented lines will be properly indented in the output, as well. Block comments may also be used. They may span multiple lines.

Block comment indents are preserved, as well.

  i = 0; // Comments with code are not
  j = 1; /* interpreted as reST. */

In using CodeChat with Sphinx, I’ve developed a set of guidelines to make my code more consistent and readable. These are my recommendations. Refer to the examples in A programmer’s word processor to see these principles applied to actual source code.

• Carefully organize your code using sections. Based on Sphinx recommendations for sections, use:
  • In a TOC-containing document, use @ with overline for large parts. See, for example, CodeChat’s table of contents.
  • In a TOC-containing document use # with overline, for parts. Again, see CodeChat’s table of contents
  • In each source file, use a single * with overline near the top of the file, giving the name of the file and a very brief description. See the title above as an example.
  • In a source file, use multiple = for sections. Then, repeat for finer-grained items, as shown below. The source files in this package, such as setup.py - Package and install CodeChat, demonstrate this.
  • Use - for subsections.
  • Use ^ for subsubsections.
  • Use " for subsubsubsections.
• Rather than leaving blank lines between code and a section, place empty comments. This makes the resulting HTML look better by suppressing an unnecessary newline. For example, correct use is:

    void foo() {
    }

Title

Note that the comment character before the section title suppresses a newline.

Incorrect:

    void foo {
    }
 

Title

Note the unnecesary newline before the section title above.

• Headings may be indented, but this causes problems in the resulting HTML by indenting too much. Avoid this.

    void foo(int i_sum) {
        if (i_sum) {

Indented heading – bad

This comment isn’t indented as it should be, one bad result of indenting a heading.

            assert(i_sum > 1);

Another indented heading – bad

The indentation on this heading is wrong, too, another bad result. In fact, everything will be indented until the next heading. For example, the following code and comments will be extremely overindented.

            bar(i_sum);

Overindented text.

An unindented heading – correct

Now, text and code will be indented correctly.

• Document functions, classes, parameters, etc. on the preeceding line. For example:

  Provide a series of utilities to assist in eating a balanced diet.

    class DietBalancer {

Compute the number of bananas needed to provide a balanced diet.

Return value: Amount of bananas, in pounds, needed.

        int bananas_for_balanced_diet(

Amount of apples available, in pounds.

          apples,

Amount of oranges available, in pounds.

          orangs) {
 

Per myPlate, the following calculations determine the needed mass of bananas.

            /// ...Code omitted...

• Insert a per-source file table of contents (such as the one at the beginning of A programmer’s word processor) to provide a quick overview of the file’s structure.
• Avoid long lines; wrap your lines at 80 characters. Many editors aren’t configured to wrap lines nicely, or can’t do it well. They certainly won’t wrap bulleted lists, indentation, etc. well. Make sure your code is readable in a plain text editor or IDE, not only when viewed using CodeChat.
• Avoid tabs. They make the resulting HTML less predictable. A tab after the inital comment character(s) won’t be recognized as a reST-formatted comment.
• Use in-line hyperlinks (as in this document), rather than separating the link and its definition. Include hyperlinks to essential information you find while searching the web: that magic post from stackoverflow that solved (or promised to and didn’t) your problem. Link to a reference manual when calling from a documented API. Link to other parts of your code that cooperate with the lines you’re documenting.
• When commenting code out, use /// (C, C++ – although #if 0 / #endif is better), ## in Python, etc. For example:

Don’t do this now, still debugging.

    /// exit(0);

Use a similar structure to get a monospaced font when necessary. For example:

    ///       Max  Prefix   Hit ratio
    dump_objs(23,  "test_", 3.05);

• Use directives, such as note, to place highly visible reminders in your code.

Note

Need to work on this.

• Use reST comments to hide text in the output. At the top of the this file, the file’s license is present in the source, but not included in the output through the use of reST comments.
• Create diagrams, such as state diagrams, flow charts, etc. by embedding Graphviz statements in your source code. It’s painful to get started, but changing them as the code changes is a snap.
• Embed figures to better explain your program. For example, use external drawing programs to produce diagrams. Take a screenshot of a GUI or some graphical result from your code. Scan and mark up a datasheet, showing what choices you made in your code. Take a picture of your code in use – GPS nagivation on a smart phone, etc.
• Avoid the use of Sphinx domains. They’re helpful when writing a separate document which describes code; literate programming intermingles code and documentation to produce an executable document, making it much easier to keep the content updated and relevant.