configure Support for Plugins MySQL

This section covers guidelines for C/C++ code for the MySQL server. The guidelines do not necessarily apply for other projects such as MySQL Connector/J or MaxDB.

Indentation and Spacing

  • Use spaces for space. Do not use tabs (t). See the editor configuration tips at the end of this section for instructions on configuring a vim or emacs editor to use spaces instead of tabs.
  • Use line feed (n) for line breaks. Do not use carriage return + line feed (rn); that can cause problems for other users and for builds. This rule is particularly important if you use a Windows editor.
  • To begin indenting, add two spaces. To end indenting, subtract two spaces. For example:

  • The maximum line width is 80 characters. If you are writing a longer line,try to break it at a logical point and continue on the next line with the same indenting. Use of backslash is okay; however, multi-line literals might cause less confusion if they are defined before the function start.
  • You may use empty lines(two line breaks in a row) wherever it seems helpful for readability. But never use two or more empty lines in a row. The only exception is after a function definition (see below).
  • To separate two functions, use three line breaks (two empty lines). To separate a list of variable declarations from executable statements, use two line breaks (one empty line). For example:
  • Matching'{}'(left and right braces) should be in the same column, that is,the closing '}' should be directly below the opening'{'.Do not put any non-space characters on the same line as a brace, not even a comment. Indent within braces. Exception 1: after switch there is a different rule, see below. Exception 2: if there is nothing between two braces, i.e.'{}', they should appear together. For example:
  • After switch use a brace on the same line, and do not indent the next line. For example:
  • You may align variable declarations like this:
  • When assigning to a variable, put zero spaces after the target variable name, then the assignment operator ('=' '+=' etc.), then space(s). For single assignments, there should be only one space after the equal sign. For multiple assignments,add additional spaces so that the source values line up. For example:
  • Align assignments from one structure to another, like this:
  • Put separate statements on separate lines. This applies for both variable declarations and executable statements. For example,this is wrong:
  • Put spaces both before and after binary comparison operators('>', '==', '>=', etc.),binary arithmetic operators('+' etc.),and binary Boolean operators ('||' etc.). Do not put spaces around unary operators like '!' or '++'. Do not put spaces around [de-]referencing operators like '->' or '[]'. Do not put space after '*' when '*' introduces a pointer. Do not put spaces after '('. Put one space after ')' if it ends a condition, but not if it ends a list of function arguments. For example:
  • When a function has multiple arguments separated by commas (','), put one space after each comma. For example:
  • ln= mysql_bin_log.generate_name(opt_bin_logname, "-bin", 1, buf);
  • Put one space after a keyword which introduces a condition, such as if or for or while.
  • After if or else or while, when there is only one instruction after the condition, braces are not necessary and the instruction goes on the next line, indented.
  • In function declarations and invocations: there is no space between function name and '('; there is no space or line break between '(' and the first argument; if the arguments do not fit on one line then align them. Examples:
  • (You may but don't have to split Class_name::method_name into two lines.) When arguments do not fit on one line,consider renaming them.

  • Format constructors in the following way:

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.
  • Avoid function names,structure elements, or variables that begin or end with '_'.
  • Use long function and variable names in English. This will make your code easier to read for all developers.
  • Structure types are typedef'ed to an all-upper-case identifier.
  • All #define declarations should be in upper case.
  • Enumeration names should begin with enum_.

Commenting Code

  • Comment your code when you do something that someone else may think is not “trivial”.
  • When writing multi-line comments: 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.
  • When writing single-line comments,the '/*' and '*/" are on the same line. For example:
  • 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 48 column(start the comment in column 49).
  • When commenting members of a structure or a class , align comments by 48th column. If a comment doesn't fit into one line, move it to a separate line. Do not create multiline comments aligned by 48th column.
  • Function comments are important! When commenting a function, note the IN parameters (the word IN is implicit).
    Every function should have a description unless the function is very short and its purpose is obvious. Use the following example as a template for function comments:

Additional sections can be used: WARNING,NOTES,TODO,SEE ALSO,ERRORS,REFERENCED BY.

  • All comments should be in English.
  • Put two line breaks(one empty line)between a function comment and its description.

General Development Guidelines

  • We use BitKeeper for source management.
  • You should use the MySQL 5.0 source for all new developments.The public 5.0 development branch can be downloaded with shell bk clone.
  • If you have any questions about the MySQL source, you can post them to <[email protected]> and we will answer them.
  • 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.
  • Try to write code in a lot of black boxes that can be reused or at least use a clean, easy to change interface.
  • Reuse code; There are already many algorithms in MySQL that can be reused for list handling, queues, dynamic and hashed arrays, sorting, etc.
  • Use the my_* functions like my_read()/my_write()/ my_malloc()that you can find in the mysys library,instead of the direct system calls; This will make your code easier to debug and more portable.
  • Use libstring functions(in the strings directory)instead of standard libc string functions whenever possible. For example, use bfill() and bzero() instead of memset().
  • Try to always write optimized code, so that you don't have to go back and rewrite it a couple of months later. It's better to spend 3 times as much time designing and writing an optimal function than having to do it all over again later on.
  • Avoid CPU wasteful code, even when its use is trivial, to avoid developing sloppy coding habits.
  • If you can do something in fewer lines, please do so(as long as the code will not be slower or much harder to read).
  • Do not check the same pointer for NULL more than once.
  • Never use a macro when an (inline) function would work as well.
  • Do not make a function inline if you don't have a very good reason for it. In many cases, the extra code that is generated is more likely to slow down the resulting code than give a speed increase because the bigger code will cause more data fetches and instruction misses in the processor cache.
    It is okay to use inline functions are which satisfy most of the following requirements:
  • The function is very short(just a few lines).
  • The function is used in a speed critical place and is executed over and over again.
  • The function is handling the normal case, not some extra functionality that most users will not use.
  • The function is rarely called.(This restriction must be followed unless the function translates to fewer than 16 assembler instructions.)
  • The compiler can do additional optimizations with inlining and the resulting function will be only a fraction of size of the original one.
  • Think assembly - make it easier for the compiler to optimize your code.
  • Avoid using malloc(),which is very slow. For memory allocations that only need to live for the lifetime of one thread, use sql_alloc() instead.
  • Functions return zero on success,and non-zero on error,so you can do:
  • Using goto is okay if not abused.
  • If you have an 'if' statement that ends with a 'goto' or 'return' you should NOT have an else statement:
  • Avoid default variable initializations. Use LINT_INIT() if the compiler complains after making sure that there is really no way the variable can be used uninitialized.
  • Use TRUE and FALSE instead of true and false in C++ code.This makes the code more readable and makes it easier to use it later in a C library,if needed.
  • bool exists only in C++. In C,you have to use my_bool (which is char); it has different cast rules than bool:

In C++, use bool, unless the variable is used in C code(for example the variable is passed to a C function).

  • Do not instantiate a class if you do not have to.
  • Use pointers rather than array indexing when operating on strings.
  • Never pass parameters with the &variable_name construct in C++. Always use a pointer instead!

The reason is that the above makes it much harder for the one reading the caller function code to know what is happening and what kind of code the compiler is generating for the call.

  • Do not use the %p marker of printf()(fprintf(),vprintf(),etc) because it leads to different outputs(for example on some Linux and Mac OS X the output starts with 0x while it does not on some Solaris). Use 0x%lx instead, even if it causes a truncation on some 64-bit platforms. Being sure that there is always 0x enables us to quickly identify pointer values in the DBUG trace.
  • Relying on loop counter variables being local to the loop body if declared in the for statement isnot portable. Some compilers still don't implement this ANSI C++ specification. The symptom ofsuch use is an error like this:

Suggested mode in emacs:

DBUG Tags

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 doesn't 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.


Face Book Twitter Google Plus Instagram Youtube Linkedin Myspace Pinterest Soundcloud Wikipedia

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

MySQL Topics