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