MySQL  8.0.27
Source Code Documentation
coding_guidelines.h
Go to the documentation of this file.
1 /* Copyright (c) 2017, 2021, Oracle and/or its affiliates.
2 
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6 
7 This program is also distributed with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have included with MySQL.
13 
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License, version 2.0, for more details.
18 
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22 
23 /**
24  @page GENERAL_DEVELOPMENT_GUIDELINES General Development Guidelines
25 
26  We use Git for source management.
27 
28  You should use the TRUNK source tree (currently called
29  "mysql-trunk") for all new development. To download and set
30  up the public development branch, use these commands:
31 
32  ~~~~~~~~~~~~~~~~
33  shell> git clone https://github.com/mysql/mysql-server.git mysql-trunk
34  shell> cd mysql-trunk
35  shell> git branch mysql-trunk
36  ~~~~~~~~~~~~~~~~
37  Before making big design decisions, please begin by posting a
38  summary of what you want to do, why you want to do it, and
39  how you plan to do it. This way we can easily provide you
40  with feedback and also discuss it thoroughly. Perhaps another
41  developer can assist you.
42 
43  - @subpage CODING_GUIDELINES_OF_SERVER
44  - @subpage NAMING_CONVENTION
45  - @subpage COMMENTING_CODE
46  - @subpage HEADER_FILE
47  - @subpage EXAMPLE_SETUP_FOR_CTAGS
48 */
49 
50 /**
51  @page CODING_GUIDELINES_OF_SERVER Legacy C++ Coding Guidelines of MySQL Server
52 
53  This section covers guidelines for C++ code for the MySQL
54  server, old code only. (New code should follow Google C++ coding style.)
55  The guidelines do not necessarily apply for other
56  projects such as MySQL Connector/J or Connector/ODBC.
57 */
58 
59 /**
60  @page NAMING_CONVENTION Legacy Naming Conventions
61 
62  - For identifiers formed from multiple words, separate each
63  component with underscore rather than capitalization.
64  Thus, use my_var instead of myVar or MyVar.
65 
66  - Avoid capitalization except for class names; class names
67  should begin with a capital letter.
68  This exception from Google coding guidelines exists
69  because the server has a history of using My_class. It will
70  be confusing to mix the two (from a code-review perspective).
71 
72  ~~~~~~~~~~~~~~~~
73  class Item;
74  class Query_arena;
75  class Log_event;
76  ~~~~~~~~~~~~~~~~
77 
78  - Avoid function names, structure elements, or variables
79  that begin or end with '_'.
80 
81  - Use long function and variable names in English. This
82  makes your code easier to read for all developers.
83 
84  - We used to have the rule: "Structure types are typedef'ed
85  to an all-upper-case identifier." That rule has been
86  deprecated for C++ code. Do not add typedefs for
87  structs/classes in C++.
88 
89  - All \#define declarations should be in upper case.
90 
91  ~~~~~~~~~~~~~~~~
92  #define MY_CONSTANT 15
93  ~~~~~~~~~~~~~~~~
94 
95  - Enumeration names should begin with enum_.
96 
97  - Function declarations (forward declarations) have
98  parameter names in addition to parameter types.
99 */
100 
101 /**
102  @page COMMENTING_CODE Legacy Commenting Style
103 
104  - Comment your code when you do something that someone else
105  may think is not trivial.
106 
107  - Comments for pure virtual functions, documentation for
108  API usage should precede (member, or
109  non-member) function declarations. Descriptions of
110  implementation details, algorithms, anything that does
111  not impact usage, should precede the
112  implementation. Please try to not duplicate information.
113  Make a reference to the declaration from the
114  implementation if necessary. If the implementation and
115  usage are too interleaved, put a reference from the
116  interface to the implementation, and keep the entire
117  comment in a single place.
118 
119  - Class comments should precede the class
120  declaration.
121 
122  - When writing multi-line comments please put the '<em>*</em>' and
123  '<em>*</em>/' on their own lines, put the '<em>*</em>/' below the
124  '/<em>*</em>', put a line break and a two-space indent after the
125  '/<em>*</em>', do not use additional asterisks on the left of the comment.
126 
127  <div style="margin-left:30px">
128  <table style="background-color:#E0E0E0"><tr><td style="width:670px"><pre>
129  /<em>*</em>
130  This is how a multi-line comment in the middle of code
131  should look. Note it is not Doxygen-style if it is not at the
132  beginning of a code enclosure (function or class).
133  <em>*</em>/
134 
135  /<em>* *********</em>This comment is bad. It's indented incorrectly, it has
136  <em>*</em> additional asterisks. Don't write this way.
137  <em>* **********</em>/</pre>
138  </td></tr></table></div>
139 
140  - When writing single-line comments, the '/<em>*</em>' and '<em>*</em>/" are
141  on the same line. For example:
142 
143  <div style="margin-left:30px">
144  <table style="background-color:#E0E0E0"><tr><td style="width:670px">
145  /<em>*</em> We must check if stack_size = Solaris 2.9 can return 0 here.
146  <em>*</em>/</td></tr></table></div>
147 
148  - Single-line comments like this are okay in C++.
149 
150  <div style="margin-left:30px">
151  <table style="background-color:#E0E0E0"><tr><td style="width:670px">
152  /<em></em>/ We must check if stack_size = Solaris 2.9 can return 0 here.
153  </td></tr></table></div>
154 
155 
156  - For a short comment at the end of a line, you may use
157  either /<em>*</em> ... *<em></em>/ or a // double slash. In C files or in
158  header files used by C files, avoid // comments.
159 
160  - Align short side // or /<em>*</em> ... <em>*</em>/ comments by 48th column
161  (start the comment in column 49).
162 
163  <div style="margin-left:30px">
164  <table style="background-color:#E0E0E0"><tr><td style="width:670px">
165  { qc*= 2; /<em>*</em> double the estimation <em>*</em>/ }
166  </td></tr></table></div>
167 
168  - All comments should be in English.
169 
170  - Each standalone comment must start with a Capital letter.
171 
172  - There is a '.' at the end of each statement in a comment
173  paragraph, including the last one.
174 
175  <div style="margin-left:30px">
176  <table style="background-color:#E0E0E0"><tr><td style="width:670px"><pre>
177  /<em>*</em>
178  This is a standalone comment. The comment is aligned to fit 79
179  characters per line. There is a period at the end of each sentence.
180  Including the last one.
181  <em>*</em>/</pre>
182  </td></tr></table></div>
183 
184  - Every structure, class, method or function should have a
185  description unless it is very short and its purpose is
186  obvious.
187 
188  - Use the following example as a template for function or
189  method comments.
190 
191  + Please refer to the Doxygen Manual
192  (http://www.stack.nl/~dimitri/doxygen/manual.html)
193  for additional information.
194 
195  + Note the IN and OUT parameters. IN is implicit, and
196  can (but usually should not) be specified with the
197  \@param[in] tag. For OUT and INOUT parameters you should
198  use \@param[out] and \@param[in,out] tags,
199  respectively.
200 
201  + Parameter specifications in \@param section start
202  with lowercase and are not terminated with a full
203  stop/period.
204 
205  + Section headers are aligned at two spaces. This must
206  be a sentence with a full stop/period at the end.
207  If the sentence must express a subject that
208  contains a full stop such that Doxygen would be
209  fooled into stopping early, then use \@brief and
210  \@details to explicitly mark them.
211 
212  + Align \@retval specifications at four spaces if they
213  follow a \@return description. Else, align at two
214  spaces.
215 
216  + Separate sections with an empty line. <br>
217 
218  + All function comments should be no longer than 79
219  characters per line.
220 
221  + Put two line breaks (one empty line) between a
222  function comment and its description. <br>
223 
224  + Doxygen comments: Use <em>/</em>** ... *<em>/</em> syntax and not ///
225 
226  + Doxygen command: Use '@' and not '\' for doxygen commands.
227 
228  <div style="margin-left:30px">
229  <table style="background-color:#E0E0E0"><tr><td style="width:670px">
230  /<em>**</em><pre>
231  Initialize SHA1Context.
232 
233  Set initial values in preparation for computing a new SHA1 message digest.
234 
235  \@param[in,out] context the context to reset
236 
237  \@return Operation status
238  \@retval SHA_SUCCESS OK
239  \@retval != SHA_SUCCESS sha error Code
240  <em>*</em>/
241 
242  int sha1_reset(SHA1_CONTEXT *context)
243  {
244  ...</pre>
245  </td></tr></table></div>
246 */
247 
248 /**
249  @page HEADER_FILE Header Files
250 
251  - Use header guards. Put the header guard in the first
252  line of the header, before the copyright. Use an
253  all-uppercase name for the header guard. Derive the
254  header guard name from the file base name, and append
255  _INCLUDED to create a macro name. Example: sql_show.h ->
256  SQL_SHOW_INCLUDED.
257 
258  - Include directives shall be first in the file. In a class
259  implementation, include the header file containing the class
260  declaration before all other header files, to ensure
261  that the header is self-sufficient.
262 
263  - Every header file should be self-sufficient in the sense
264  that for a header file my_header.h, the following should
265  compile without errors:
266 
267  ~~~~~~~~~~~~~~~~
268  #include "my_header.h"
269  ~~~~~~~~~~~~~~~~
270 
271  An exception is made for generated files; for example, those
272  generated by Yacc and Lex, because it is not possible to
273  rewrite the generators to produce "correct" files.
274 */
275 
276 /**
277  @page EXAMPLE_SETUP_FOR_CTAGS Example Setup for ctags
278 
279  Put this configuration into your ~/.ctags file:
280  @verbatim
281  --c++-kinds=+p
282  --fields=+iaS
283  --extra=+q
284  --langdef=errmsg
285  --regex-errmsg=/^(ER_[A-Z0-9_]+)/\1/
286  --langmap=errmsg:(errmsg*.txt),c:+.ic,yacc:+.yy
287  @endverbatim
288 */
289 
290 /**
291  @page DBUG_TAGS DBUG Tags
292 
293  <p>The full documentation of the DBUG library is in files dbug/user.* in the
294  MySQL source tree. Here are some of the DBUG tags we now use:</p>
295 
296  - enter
297 
298  Arguments to the function.
299 
300  - exit
301 
302  Results from the function.
303 
304  - info
305 
306  Something that may be interesting.
307 
308  - warning
309 
310  When something does not go the usual route or may be wrong.
311 
312  - error
313 
314  When something went wrong.
315 
316  - loop
317 
318  Write in a loop, that is probably only useful when debugging the loop.
319  These should normally be deleted when you are satisfied with the code
320  and it has been in real use for a while.
321 
322  <br>
323  Some tags specific to mysqld, because we want to watch these carefully:
324 
325  - trans
326 
327  Starting/stopping transactions.
328 
329  - quit
330 
331  info when mysqld is preparing to die.
332 
333  - query
334 
335  Print query.
336 
337 */