[Spice-devel] spice-server style documentation
Christophe Fergeau
cfergeau at redhat.com
Mon May 9 15:32:32 UTC 2016
Hey,
On Mon, May 09, 2016 at 11:09:40AM -0400, Frediano Ziglio wrote:
> I think it's time to update this document
>
> >
> > 1. C and C++ style
> >
> > All of the following are applicable for both c and c++, except for section 25
> > which is c++ extension.
> >
>
> This file is in spice-server which is not much C++ but this paragraph is
> not going to hurt.
spice-server used to have a spice/client directory with c++ code, long
gon.
>
> > 2. Source Files
> >
> > 2.1. Names
> > Use lower case and separate words using underscore (e.g., file_name.c,
> > header.h).
> >
>
> Now we use dashes, not underscores.
>
> > Use cpp file extension for c++ source files and hpp extension for c++
> > template files. Use standard file extension for c source and header files.
> > 2.2. Line width
> > No more then 100 character on a single line
>
> There are lines with more than 140 characters.
I personally don't think we should get in that habit, and that 100
characters is plenty enough. Fine with me if we go with a bigger limit.
> > 5. Static storage initialization
> >
> > To improve code readability, explicitly initialize variables that depend on
> > default initialization with zero/null.
> >
>
> Does it still apply?
"Do not use static" ? :) Anyway, I don't think it hurts to have that.
>
> > 6. Fixme and todo
> >
> > Comments that are prefixed with “fixme” describe a bug that need to be fixed.
> > Generally, it is not allowed to commit new code having “fixme” comment.
> > Committing “fixme” is allowed only for existing bugs. Comments that are
> > prefixed with “todo” describe further features, optimization or code
> > improvements, and they are allowed to be committed along with the relevant
> > code.
> >
>
> Most are TODO and FIXME now.
>
> > 7. ASSERT
> >
> > Use it freely. ASSERT helps testing function arguments and function results
> > validity. ASSERT helps detecting bugs and improve code readability and
> > stability.
> >
>
> This is quite outdated
>
> > 8. sizeof
> >
> > Apply function style to sizeof (i.e., use sizeof(x))
> >
> > 9. const
> >
> > Use const keyword when applicable to improve code reliability and celerity.
> >
> > 10. goto
> >
> > Using goto is allowed in c code for error handling. In any other case it will
> > be used only as a special exception.
> >
>
> not really true, in some code we use quite a lot of gotos.
>
> > 11. Defining Constant values
> >
> > Use defines for constant values for improving readability and ease of
> > changes. Alternatively, use global const variables.
> >
> >
> >
> > 12. void argument
> >
> > Don't add explicitly void argument in functions without arguments. (i.e.,
> > void function_name() is OK)
> >
>
> This apply only to C++.
>
> > 13. Short functions
> >
> > Try to split code to short functions, each having simple functionality, in
> > order to improve code readability and re-usability. Prefix with inline short
> > functions or functions that were splitted for readability reason.
> >
> > 14. Return on if
> >
> > Try to return immediately on if in places that can reduce indentation level.
> >
> > Example:
> >
> > prefer
> >
> > void function(int *n)
> > {
> > if (!n) {
> > return;
> > }
> > ...
> > }
> >
> > on
> >
> > void function(int *n)
> > {
> > if (!n) {
> > return;
> > } else {
> > ...
> > }
> > }
> >
> > 15. Names
> >
> > Don't underestimate the importance of name choosing. Good names make the code
> > more easy to understand and reduce the required level of code documentation.
> > When choosing names, prefer long meaningful names over short vague name.
> >
> > Variable and Function names – use lower case and separate words using
> > underscore (e.g., sample_variable_name)
> >
> > Structures, class and enum names – one or more words, each word start with
> > upper case (e.g., Name, SampleStructName)
> >
> > Defines and enum items names – uppercase words separated using underscores
> > (e.g., NAME, SAMPLE_DEFINE_NAME)
> >
> > 16. Optimization
> >
> > Keep optimization to fast path code. Prefer safe, clear and easy to maintain
> > coding for code that is not on the fast path.
> >
> > 17. Spacing
> >
> > Use spacing for improving code readability.
> >
> > for (i = 0; i < 10; ++i) {
> > some_func(var, i * i + *ptr, &var, sizeof(var));
> > }
> >
>
> we should specify something more than this
>
> > 18. Function Indentation
> >
> > No spaces between function name to left bracket.
> > Curly bracket start on new line.
> > Functions must be padded with empty lines on both sides
> >
> > void function(type1 arg1, type2 arg2, type2 arg3)
> > {
> > ...
> > }
> >
> > In case of a new line in arguments list, align it to the first argument type.
> >
> > void function(type1 arg1,
> > type2 arg2,
> > type3 arg3)
> > Or
> > void function(type1 arg1, type2 arg2,
> > type3 arg3)
> >
> > New line is acceptable only in arguments list
> >
>
> Still true, sometimes this make the lines quite long if functions names
> are quite long. Could we accept something like
>
> type
> function_name(args...)
> {
> ...
> }
>
> ? Looks like some functions use this style already.
>
> >
> > 19. Branching indentation
> >
> > Add space after a branch keyword and after the right bracket.
> > Curly bracket starts on the same line the branch starts.
> > Place curly brackets after all control flow constructs even where optional.
> > This convention reduces branching bugs that are difficult to detect. It also
> > makes it easier to add logging messages during debugging since it
> > eliminates the need to add the brackets.
> >
> >
> > if (condition) {
> > ...
> > } else if (condition) {
> > ...
> > } else {
> > ...
> > }
> >
> > In case of long condition statement, prefer having additional temporary
> > variable over multiple line condition statement.
> >
> > In case of new line in condition statement.
> >
> > if (long_name && very_long_name && very_long ||
> > var_name) {
> >
> > or indent using two tabs
> >
>
> I don't think we indent that way.
>
> > if (long_name && very_long_name && long_name ||
> > var_name) {
> >
> > Break function arguments list in long condition statement according to
> > section 18.
> >
> >
> > while (condition) {
> > ...
> > }
> >
> > do {
> > ...
> > } while (condition);
> >
> > for (i = x; i < y; i++) {
> > ...
> > }
> >
> >
> > switch (x) {
> > case A: {
> > ...
> > break;
> > }
> > case B:
> > ...
> > ...
> > break;
> > default:
> > ...
> > }
> >
> > 20. Types indentation
> >
> > struct StructName {
> > type1 name1;
> > type2 name2;
> >
> > ...
> > };
> >
> > enum {
> > A,
> > B,
> > C = 10,
> > D,
> > };
> >
> > union {
> > type1 name1;
> > type2 name2;
> > ...
> > } u;
> >
> > 21. Vertical indentation
> >
> > Use one space no tabs and no vertical alignment.
> >
> > long var_name_1 = 7;
> > int var_name_2 = 1111l;
> > unsigned long long_var_name_1 = 666;
> > char long_var_name_1 = 'a';
> >
> > void f1(int a, char ch);
> > unsigned long f2(int a, char ch);
> >
> > 22. Multi line macro indentation
> >
> > #define MACRO_NAME(a, b, c) { \
> > int ab = a + c; \
> > int ac = a + b; \
> > int bc = b + c; \
> > f(ab, ac, bc); \
> > }
> >
> > 23. Multi line array indentation
> >
> > char *array[] = {
> > “item_1",
> > "item_2",
> > "item_3",
> > };
> >
> > 24. C++
> >
> > C++ style extends C Coding style
> > 24.1. One super
> >
> > Avoid having more then one super class. Inherit from one super class and
> > multiple interfaces (abstract class) for having multiple inheritance.
> >
> > 24.2. Data members
> >
> > Prefix all protected and private data members with underscore (i.e.,
> > _member_name).
>
> Don't think apply anymore
>
> > Using public data members is allowed only as an exception. Use getters and
> > setters instead.
> >
> > 24.3. Object reference
> >
> > For code clarity use object reference (i.e., Type& var) in places where it is
> > not allow to have null pointer and is not permitted to release the object.
> >
> > 24.4. Templates
> >
> > The use of c++ templates is limited to simple containers.
> >
> > 24.5. '*' and '&'
> >
> > '*' and '&' , should be directly connected with the type names.
> >
> > Example:
> >
> > void function(int* i, int& n);
> >
> > 24.6. Class indentation
> >
> > class ClassName: public SuperClass, public FirstInterface,
> > public SecondInterface {
> > public:
> > ClassName();
> > virtual ~ClassName();
> >
> > type public_function_1(type var);
> > type public_function_2();
> > ...
> >
> > protected:
> > type protected_function_1(type var);
> > type protected_function_2();
> > ...
> >
> > private:
> > type private_function_1(type var);
> > type private_function_2();
> > ...
> >
> > public:
> > type public_member_1;
> > type public_member_2;
> > ...
> >
> > protected:
> > type _protected_member_1;
> > type _protected_member_2;
> > ...
> >
> > private:
> > type _private_member_1;
> > type _private_member_2;
> > ...
> > };
> > 24.7. Constructor indentation
> >
> > ClassName::ClassName(type1 arg1, type2 arg2,type3 arg3,
> > type4 arg4)
> > : SuperClass(arg1, arg2)
> > , _member_1 (arg3)
> > , _member_2 (arg4)
> > ...
> > {
> > ...
> > }
> >
> > 24.8. bool
> >
> > Use built-in bool 'true' and 'false' instead of TRUE and FALSE.
> >
> > 24.9. Operator overloading
> >
> > Avoid using operator overloading. It is only allowed as an exception.
> >
> > 24.10. AutoRef and AutoPtr
> >
> > Use AutoRef and AutoPtr style object for automatic object release. Using
> > those objects simplify function cleanups and exception handling.
> >
>
> outdated
>
> > 25. Spice client
> > 25.1. #ifdef PLATFORM
> >
> > Use #ifdef <platform> only in cases of different logic that depends on
> > platform. In all other case add common interface (e.g., in platform.h) and
> > keep specific platform implementation in platform directory (e.g.,windows).
>
> > 25.2. Use standard macros
> > LOG_INFO
> > LOG_WARN
> > LOG_ERROR
> > ASSERT
> > PANIC
> > DBG
> > THROW
> > THROW_ERR
> >
>
> outdated
>
> I would add some function naming and abbreviations like "dcc", "rcc" and so on.
>
> Also the .odt format is quite bad in git as diff is not working that fine
> with binary files.
Yeah, I guess it can just be copied and pasted to a .txt file.
Christophe
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <https://lists.freedesktop.org/archives/spice-devel/attachments/20160509/24603d72/attachment.sig>
More information about the Spice-devel
mailing list