style_guide.cpp - Style recommendations for CodeChat with reStructuredText markup

Note

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

Syntax

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 delimiter.

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

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

…becomes…

A line containing only a comment in interpreted 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. */

Guidelines

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 CodeChat 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.

    • In a TOC-containing document use # with overline, for parts. Again, see CodeChat

    • 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.

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

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

Indented heading – bad

The next line of code 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 preceding 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.

            unsigned int apples,

Amount of oranges available, in pounds.

            unsigned int oranges) {
 

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

            /// ...Code omitted...
  • Use the |docname| replacement in the title to insert this file’s name. See the top of this file for an example.

  • Insert a per-source file table of contents (such as the one at the beginning of CodeChat) to provide a quick overview of the file’s structure.

  • Avoid tabs. They make the resulting HTML less predictable. A tab after the initial comment character(s) won’t be recognized as a reST-formatted comment.

  • Select tab stops and stick with them. Don’t indent based on the size of the preceding reST element – this makes code difficult to edit. For example, note how this list is constructed: not as * A bullet here..., but *    A bullet here to align with tab stops. (Per the preceding point, no tabs are used, just tab stops; in this case, all indents are aligned to 4 space boundaries.)

  • 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 Stack Overflow 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 navigation 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.