/* Copyright (c) 2017, 2024, Oracle and/or its affiliates. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2.0, as published by the Free Software Foundation. This program is designed to work with certain software (including but not limited to OpenSSL) that is licensed under separate terms, as designated in a particular file or component or in included license documentation. The authors of MySQL hereby grant you an additional permission to link the program and your derivative works with the separately licensed software that they have either included with the program or referenced in the documentation. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License, version 2.0, for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ /** @page GENERAL_DEVELOPMENT_GUIDELINES General Development Guidelines We use Git for source management. You should use the TRUNK source tree (currently called "mysql-trunk") for all new development. To download and set up the public development branch, use these commands: ~~~~~~~~~~~~~~~~ shell> git clone https://github.com/mysql/mysql-server.git mysql-trunk shell> cd mysql-trunk shell> git branch mysql-trunk ~~~~~~~~~~~~~~~~ Before making big design decisions, please begin by posting a summary of what you want to do, why you want to do it, and how you plan to do it. This way we can easily provide you with feedback and also discuss it thoroughly. Perhaps another developer can assist you. - @subpage CODING_GUIDELINES_OF_SERVER - @subpage NAMING_CONVENTION - @subpage COMMENTING_CODE - @subpage HEADER_FILE - @subpage EXAMPLE_SETUP_FOR_CTAGS */ /** @page CODING_GUIDELINES_OF_SERVER Legacy C++ Coding Guidelines of MySQL Server This section covers guidelines for C++ code for the MySQL server, old code only. (New code should follow Google C++ coding style.) The guidelines do not necessarily apply for other projects such as MySQL Connector/J or Connector/ODBC. */ /** @page NAMING_CONVENTION Legacy Naming Conventions - For identifiers formed from multiple words, separate each component with underscore rather than capitalization. Thus, use my_var instead of myVar or MyVar. - Avoid capitalization except for class names; class names should begin with a capital letter. This exception from Google coding guidelines exists because the server has a history of using My_class. It will be confusing to mix the two (from a code-review perspective). ~~~~~~~~~~~~~~~~ class Item; class Query_arena; class Log_event; ~~~~~~~~~~~~~~~~ - Avoid function names, structure elements, or variables that begin or end with '_'. - Use long function and variable names in English. This makes your code easier to read for all developers. - We used to have the rule: "Structure types are typedef'ed to an all-upper-case identifier." That rule has been deprecated for C++ code. Do not add typedefs for structs/classes in C++. - All \#define declarations should be in upper case. ~~~~~~~~~~~~~~~~ #define MY_CONSTANT 15 ~~~~~~~~~~~~~~~~ - Enumeration names should begin with enum_. - Function declarations (forward declarations) have parameter names in addition to parameter types. */ /** @page COMMENTING_CODE 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 (http://www.stack.nl/~dimitri/doxygen/manual.html) 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)
  {
    ...
*/ /** @page HEADER_FILE Header Files - Use header guards. Put the header guard in the first line of the header, before the copyright. Use an all-uppercase name for the header guard. Derive the header guard name from the file base name, and append _INCLUDED to create a macro name. Example: sql_show.h -> SQL_SHOW_INCLUDED. - Include directives shall be first in the file. In a class implementation, include the header file containing the class declaration before all other header files, to ensure that the header is self-sufficient. - Every header file should be self-sufficient in the sense that for a header file my_header.h, the following should compile without errors: ~~~~~~~~~~~~~~~~ #include "my_header.h" ~~~~~~~~~~~~~~~~ An exception is made for generated files; for example, those generated by Yacc and Lex, because it is not possible to rewrite the generators to produce "correct" files. */ /** @page EXAMPLE_SETUP_FOR_CTAGS Example Setup for ctags Put this configuration into your ~/.ctags file: @verbatim --c++-kinds=+p --fields=+iaS --extra=+q --langdef=errmsg --regex-errmsg=/^(ER_[A-Z0-9_]+)/\1/ --langmap=errmsg:(errmsg*.txt),c:+.ic,yacc:+.yy @endverbatim */ /** @page DBUG_TAGS DBUG Tags

The full documentation of the DBUG library is in files dbug/user.* in the MySQL source tree. Here are some of the DBUG tags we now use:

- enter Arguments to the function. - exit Results from the function. - info Something that may be interesting. - warning When something does not go the usual route or may be wrong. - error When something went wrong. - loop Write in a loop, that is probably only useful when debugging the loop. These should normally be deleted when you are satisfied with the code and it has been in real use for a while.
Some tags specific to mysqld, because we want to watch these carefully: - trans Starting/stopping transactions. - quit info when mysqld is preparing to die. - query Print query. */