[Spice-devel] spice-server style documentation
Frediano Ziglio
fziglio at redhat.com
Tue May 10 09:45:40 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
>
I was thinking about the possibility of easy conversion to HTML to post
it and a bit of style. There are a lot of markup languages here and there
but I would suggest the usage of asciidoc as we already use this format/tool
for the manual.
What the guys managing the web space think about it ?
Frediano
More information about the Spice-devel
mailing list