MySQL 8.2.0
Source Code Documentation
Legacy Commenting Style
  • Comment your code when you do something that someone else may think is not trivial.
  • Comments for pure virtual functions, documentation for API usage should precede (member, or non-member) function declarations. Descriptions of implementation details, algorithms, anything that does not impact usage, should precede the implementation. Please try to not duplicate information. Make a reference to the declaration from the implementation if necessary. If the implementation and usage are too interleaved, put a reference from the interface to the implementation, and keep the entire comment in a single place.
  • Class comments should precede the class declaration.
  • When writing multi-line comments please put the '*' and '*/' on their own lines, put the '*/' below the '/*', put a line break and a two-space indent after the '/*', do not use additional asterisks on the left of the comment.
   This is how a multi-line comment in the middle of code
   should look.  Note it is not Doxygen-style if it is not at the
   beginning of a code enclosure (function or class).

 /* *********This comment is bad. It's indented incorrectly, it has
 *            additional asterisks. Don't write this way.
 *  **********/
  • When writing single-line comments, the '/*' and '*/' are on the same line. For example:
/* We must check if stack_size = Solaris 2.9 can return 0 here. */
  • Single-line comments like this are okay in C++.
// We must check if stack_size = Solaris 2.9 can return 0 here.
  • For a short comment at the end of a line, you may use either /* ... */ or a // double slash. In C files or in header files used by C files, avoid // comments.
  • Align short side // or /* ... */ comments by 48th column (start the comment in column 49).
{ qc*= 2; /* double the estimation */ }
  • All comments should be in English.
  • Each standalone comment must start with a Capital letter.
  • There is a '.' at the end of each statement in a comment paragraph, including the last one.
   This is a standalone comment. The comment is aligned to fit 79
   characters per line. There is a period at the end of each sentence.
   Including the last one.
  • Every structure, class, method or function should have a description unless it is very short and its purpose is obvious.
  • Use the following example as a template for function or method comments.

    • Please refer to the Doxygen Manual ( for additional information.
    • Note the IN and OUT parameters. IN is implicit, and can (but usually should not) be specified with the @param[in] tag. For OUT and INOUT parameters you should use @param[out] and @param[in,out] tags, respectively.
    • Parameter specifications in @param section start with lowercase and are not terminated with a full stop/period.
    • Section headers are aligned at two spaces. This must be a sentence with a full stop/period at the end. If the sentence must express a subject that contains a full stop such that Doxygen would be fooled into stopping early, then use @brief and @details to explicitly mark them.
    • Align @retval specifications at four spaces if they follow a @return description. Else, align at two spaces.
    • Separate sections with an empty line.
    • All function comments should be no longer than 79 characters per line.
    • Put two line breaks (one empty line) between a function comment and its description.
    • Doxygen comments: Use /** ... */ syntax and not ///
    • Doxygen command: Use '@' and not '\' for doxygen commands.
       Initialize SHA1Context.
       Set initial values in preparation for computing a new SHA1 message digest.
       @param[in,out]  context  the context to reset
       @return Operation status
         @retval SHA_SUCCESS      OK
         @retval != SHA_SUCCESS   sha error Code
     int sha1_reset(SHA1_CONTEXT *context)