LLILC Coding Conventions and Commenting Style

LLILC Coding Guidelines

General Coding Guidelines

The LLILC project is structured as a subproject of LLVM so we are using the same coding conventions as LLVM. The LLVM coding conventions are at http://llvm.org/docs/CodingStandards.html.

Commenting Guidelines

In particular http://llvm.org/docs/CodingStandards.html#commenting has guidelines for commenting code and using Doxygen markup. For a complete description of Doxygen markup see <>.

We can summarize these as follows:

• Use the "///" style of comment unless that file is written in C or may be included into a C file.

• For Doyxygen markup, use the "" form, e.g. \brief, rather than the "@" form, e.g. @brief.

• Use the \file command to turn the standard file header into a file-level comment.

• Include descriptive \brief paragraphs for all public interfaces (public classes, member and non-member functions). Explain API use and purpose in \brief paragraphs, don’t just restate the information that can be inferred from the API name. Put detailed discussion into separate paragraphs.

• To refer to parameter names inside a paragraph, use the \p name command. Don’t use the \arg name command since it starts a new paragraph that contains documentation for the parameter.

• Wrap non-inline code examples in \code ... \endcode.

• To document a function parameter, start a new paragraph with the \param name command. If the parameter is used as an out or an in/out parameter, use the \param [out] name or \param [in,out] name command, respectively.

• To describe function return value, start a new paragraph with the \returns command

• For public classes and class members, put the Doxygen comments in the header file. For private classes or members put the comments in the implementation file.

In addition to these recommendations from the LLVM coding standards I have the following recommendations:

• Doxygen supports Markdown, so use it in your comments when it can do what you want. See http://www.stack.nl/~dimitri/doxygen/manual/markdown.html

• In order to provide greater logical clarity on the semantics of classes and methods I suggest using the Doxygen \pre, \post, and \invariant special commands to specify method preconditions and postconditions and class invariants.

Use of LLVM I/O APIs

Rather than using the printf family of output functions the LLILC team uses the LLVML I/O APIs. This is a simplified form of C++ output.

• The base type is raw_ostream.
• Derived classes are:
  • raw_fd_ostream, for output to a file descriptor. Two of these are made and accessed as follows:
    • outs() is connected to stdout
    • errs() is connected to stderr.
    • dbgs() is a debug stream that is connected to stderr but which may optionally have circular buffering but by default it is an unbuffered connection to errs().
  • raw_string_ostream connects to a std::string given in its
    • constructor. Any output to that stream is appended to the end of the string.
• As with C++ the "<<" operator has overloads for outputting all the common data types.
• In addition the form "<< format(formatstring, args)" may be used to get the usual printf-stype formatting to a stream.