New sections for our code style guide

I’d like to add these sections to our code style guide. Are there any objections?

Most of our code does not follow these guidelines yet. Once we have added them to the official style guide, cleanup commits have more justification.

More guidelines can be added in the future. However, these are the once I care about right now. Some of the rules below have many alternatives that are just as good imo. I just picked one, so that we can make our code more consistent.

C++ Namespaces

Namespaces have lower case names.

Blender uses the top-level blender namespace. Most code should be in nested namespaces like blender::deg or blender::io::alembic. The exception are common data structures in the blenlib folder, that can exist in the blender namespace directly (e.g. blender::float3).

Prefer using nested namespace definition like namespace blender::io::alembic { ... } over namespace blender { namespace io { namespace alembic { ... }}}.

Tests should be in the same namespace as the code they are testing.

C++ Containers

Prefer using our own containers over their corresponding alternatives in the standard library. Common containers are blender::Vector, blender::Set and blender::Map.

Prefer using blender::Span<T> as function parameter over const blender::Vector<T> &.

Class Member Names

Non-public data members of a class should have an underscore as suffix. Public data members should not have this suffix.

Class Layout

Classes should be structured as follows. Parts that are not needed by a specific class should just be skipped.

class X {
  /* using declarations */
  /* static data members */
  /* non-static data members */

  /* default constructor */
  /* other constructors */
  /* copy constructor */
  /* move constructor */

  /* destructor */

  /* copy assignment operator */
  /* move assignment operator */
  /* other operator overloads */

  /* all public static methods */
  /* all public non-static methods */

  /* all protected static methods */
  /* all protected non-static methods */

  /* all private static methods */
  /* all private non-static methods */

Variable Scope

Try to keep the scope of variables as small as possible.

/* Don't: */
int a, b;

a = ...;
b = ...;

/* Do: */
int a = ...;
int b = ...;


Use const whenever possible. Try to write your code so that const can be used, i.e. prefer declaring new variables instead of mutating existing ones.


:+1: from me!

(and some more text to get beyond the 20 character limit for a reply)

1 Like

Good initial guidelines, no objections. :+1:

Although I think following the core guidelines has some implications that we should check on:

  • They give clear guides as to raw-pointer vs. smart pointer vs. rvalue references, etc
    Do we also follow the guideline to use non_null (I.12)?
    What about other cases where GSL functionality is recommended? Would we introduce the GSL for that or have our own versions of it?
  • Also, what about exceptions? Personally I’m enthusiastic about the idea of using RAII and exceptions to write exception safe code (note: this is totally different from how languages like Java or Python typically use exceptions). The core guidelines recommend this too (E.6, I.10)
    Does that mean we introduce exceptions as standard way to handle errors in required tasks?
    Nevertheless, it’s a controversial feature (although I think much of this controversy is misinformed in the context of C++).
  • What about auto? It seems there’s only one guideline for using it (ES.11). But it’s a controversial feature too.

Thanks for doing this, Jacques! I have felt a section like this is sorely lacking in the current guidelines, and am happy you took the time to do it. No objections from me in adding these. Like Julian, I wonder what to do about exceptions.

Hm, you are right. Might be good to not add the link to the core guidelines just yet, without understanding the implications. The three topics you mention need more discussion. Please feel free to start a separate thread for each of these topics. I just started watching the videos you linked earlier about exceptions, but only finished the first one this morning. I need some more time to explore exceptions. When you start a new thread, you should add some motivation.

I’ll just add the other sections to the style guide for now, because everyone seems to agree on them so far.

I’ve added the guidelines to
I did not yet add the link to the c++ core guidelines there, because that needs more discussion.

It’s also used as an example in I.10: Use exceptions to signal a failure to perform a required task:

auto [val, error_code] = do_something();

Often I’m a proponent of explicit types (even in Python code I use type declarations as much as possible), but in situations like these I think the brevity really helps readability. And in this situation I would expect the do_something() function to an have explicit return type, which makes finding the type of val and error_code a mouse-hover away in any decent IDE.