multiple threads, take extra care to
document the rules and invariants surrounding multithreaded use.


Function Comments ~

Declaration comments describe use of the function; comments at the definition
of a function describe operation.

    Function Declarations ~

    Every function declaration should have comments immediately preceding it
    that describe what the function does and how to use it. These comments
    should be descriptive ("Opens the file") rather than imperative ("Open the
    file"); the comment describes the function, it does not tell the function
    what to do. In general, these comments do not describe how the function
    performs its task. Instead, that should be left to comments in the
    function definition.

    Types of things to mention in comments at the function declaration:

    - If the function allocates memory that the caller must free.
    - Whether any of the arguments can be a null pointer.
    - If there are any performance implications of how a function is used.
    - If the function is re-entrant. What are its synchronization assumptions? >c
    /// Brief description of the function.
    ///
    /// Detailed description.
    /// May span multiple paragraphs.
    ///
    /// @param arg1 Description of arg1
    /// @param arg2 Description of arg2. May span
    ///        multiple lines.
    ///
    /// @return Description of the return value.
    Iterator *get_iterator(void *arg1, void *arg2);
<

    Function Definitions ~

    If there is anything tricky about how a function does its job, the
    function definition should have an explanatory comment. For example, in
    the definition comment you might describe any coding tricks you use, give
    an overview of the steps you go through, or explain why you chose to
    implement the function in the way you did rather than using a viable
    alternative. For instance, you might mention why it must acquire a lock
    for the first half of the function but why it is not needed for the second
    half.

    Note you should not just repeat the comments given with the function
    declaration, in the `.h` file or wherever. It's okay to recapitulate
    briefly what the function does, but the focus of the comments should be on
    how it does it. >c

    // Note that we don't use Doxygen comments here.
    Iterator *get_iterator(void *arg1, void *arg2)
    {
      ...
    }


Variable Comments ~

In general the actual name of the variable should be descriptive enough to
give a good idea of what the variable is used for. In certain cases, more
comments are required.

    Global Variables ~

    All global variables should have a comment describing what they are and
    what they are used for. For example: >c

        /// The total number of tests cases that we run
        /// through in this regression test.
        const int kNumTestCases = 6;


Implementation Comments ~

In your implementation you should have comments in tricky, non-obvious,
interesting, or important parts of your code.

    Line Comments ~

    Also, lines that are non-obvious should get a comment at the end of the
    line. These end-of-line comments should be separated from the code by 2
    spaces. Example: >c

        // If we have enough memory, mmap the data portion too.
        mmap_budget = max<int64>(0, mmap_budget - index_->length());
        if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock)) {
          return;  // Error already logged.
        }
<
    Note that there are both comments that describe what the code is doing,
    and comments that mention that an error has already been logged when the
    function returns.

    If you have several comments on subsequent lines, it can often be more
    readable to line them up: >c

        do_something();                      // Comment here so the comments line up.
        do_something_else_that_is_longer();  // Comment here so there are two spaces between