MySQL
8.4.3
Source Code Documentation
coding_guidelines.h
Go to the documentation of this file.
1
/* Copyright (c) 2017, 2024, 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 designed to work 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 either included with
13
the program or referenced in the documentation.
14
15
This program is distributed in the hope that it will be useful,
16
but WITHOUT ANY WARRANTY; without even the implied warranty of
17
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18
GNU General Public License, version 2.0, for more details.
19
20
You should have received a copy of the GNU General Public License
21
along with this program; if not, write to the Free Software
22
Foundation, 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
*/
sql
coding_guidelines.h
Generated by
1.9.2