Dev:Doc/Code Style/Configuration

Configuring Software to use Blenders Code Style

This page is to help you quickly setup your development environment to edit Blender's source, this is more important for some environments then others.

Warning General warning about formatting tools since some of them can be used to automate formatting source code into Blender style (or at least a close approximation). Tools like this should not be applied globally to Blender's source-code. Typically the best way to use them is to select smaller blocks of code and format them - making sure they don't cause any problems. For 'whole-file' formatting utilities - apply to a copy of the source and then manually copy useful changes across with a differencing tool (Meld for example).

IDE

Eclipse

Tested with 4.3

Eclipse can format code in the menu: Source -> Format (Shift+Ctrl+F)

Configure C/C++ Code Style

This isn't essential for developing with eclipse but it can be handy to use sometimes to auto-format.

All options here are available as an XML below.

Open preferences: (Menu) Window -> Preferences

Go to C/C++ -> Code Style, Press New (create based on K&R)

• Indentation
  • Enable "Statements within 'switch body'"
• Braces (everything should be set to 'Same Line')
  • Set 'Function declarations to' to 'New Line'
  • Set 'Block in Case Statements' to 'New Line'
• White Space
  • Expressions
    • Initializer list
      • Disable 'After Opening Brace'
      • Disable 'Before Closing Brace'
    • Type casts
      • Disable 'After Closing perebrgesis'
• Control Statements
  • Enable "Insert new line before 'else' statement"
  • Disable "Keep 'then' statements on same line"
  • Disable "Keep 'else' statements on same line"
• Line Wrapping
  • Set 'Max line width' to 120
  • Expressions
    • Initializer list
      • Set 'Line Wrap Policy' to 'Wrap all elements, every Element on new line'
      • Set 'Indentation Policy' to Indent by 1.
• Comments
  • Enable 'Preserve white space between code and line comments if possible'

Or you can load this into eclipse direct.

Blender_Eclipse_4_3_C_CPP_code_style.xml

KDevelop

Tested with version 4.6

In the following menus...

Settings -> Configure Editor

• Appearance
  • Borders
    • Enable 'Show Line Numbers'
• Editing
  • General
    • Enable 'Show static word wrap marker'
    • Set 'Wrap words at' to 120
  • Indentation
    • Set Indent Using to 'Tabulators'
    • Set 'Tab width' to 4

MSVC

Tested with Microsoft VisualStudio 2008

Basic Setup

Go to: Tools --> Options

• Text Editor -> C/C++ -> General
  • Activate 'Line Numbers' (On by Default)
• Text Editor -> C/C++ -> Tabs
  • 'Tab Size' Set to 4
  • Activate 'Keep Tabs'

Show Guideline as 120 Chars

This one is a bit hacky in MSVC, since it is NOT supported by default, but can be reached easily over the Registry:

• Close MSVC if opened
• Open your Registry
• Navigate to the following key:
  • MSVC 2008: HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\9.0\Text Editor
  • MSVC 2008 Express: HKEY_CURRENT_USER\Software\Microsoft\VCExpress\9.0\Text Editor
• Add a String Value called "Guides"
• Set the Value to: RGB(128,0,0) 120

Now your MSVC shows at 120 chars a red line.

Xcode

"Tested with Xcode 4.6.2 (4H1003)

Go to: Xcode --> Preferences

Unfortunately Xcode doesn't have any "auto code formatting" tool, so it needs to be very carefully in using of code-style.

• Text Editing -> Editing
  • 'Page guide at column' set to 120
  • Automatically trim trailing whitespace set checked
  • Including whitespace-only lines set checked (this prevent "lines with spaces" in code)

• Text Editing -> Indentation
  • 'Prefer indent using' set to Tabs
  • 'Tab width' set to 4 spaces
  • 'Indent width' set to 4 spaces
  • 'Tab key' set to 'Inserts tab character'

NetBeans

Tested with Netbeans 8.0

Netbeans can format selected code in the menu: Source -> Format (Alt+Shift+F)

Go to: Tools --> Options

• Editor -> General...
  • Disable 'Enable Camel Case Navigation' (my personal preference)
• Editor -> Folding...
  • Disable 'Code Folding' (my personal preference)
• Editor -> Formatting...
  • Disable 'Extend Tabs to Spaces
  • 'Tab Size' Set to 4
  • 'Right Margin' Set to 120
• Editor -> Formatting -> C Language...
  • Enable 'Keep Extra Spaces'
  • Brace Placement, Function Declaration, Set to 'New Line'
  • Enable 'New Line, "else"'
  • Disable Other Spaces, After Type Cast
• Editor -> Code Completion...
  • Enable 'Case Sensitive Code Completion'

QtCreator

Tested with QtCreator 2.5.81

Note: QtCreator has no way to format existing source.

Open the Options dialog Tools -> Options

Text Editor... (main section)

• Behavior...
  • Tab Policy (set to 'Tabs Only')
  • Tab size (set to 4)
  • Align continuation lines: (Set to 'With Spaces')
  • Clean whitespace (enable)
    • 'In entire document' (disable)
    • 'Clean indentation' (disable)
• Display
  • Display Right margin at column (Enable and set to 120)
  • Highlight current line (Enable - personal preference)
  • Visualize whitespace (Enable - personal preference)

C++ (main section)

Note this duplicates some options above...

• Code Style
  • General...
    • Tab Policy (set to 'Tabs Only')
    • Tab size (set to 4)
    • Align continuation lines: (Set to 'With Spaces')
  • "switch", indent within switch -...
    • "case" or "default" (enable)
  • Alignment...
    • "Align after assignment" (enable)
    • "Add extra padding to conditions if they would align to next line" (disable)

Note, since there are not that many settings - saving an XML to load into QtCtreator isn't so useful.

Editors

Emacs

TODO

VIM

Example ~/.vimrc

" --- Extra Visual Info ---
:syn on                      " Syntax highlighting
:set spell                   " spell checking (if you like)
set showmatch                " When a bracket is inserted, briefly jump to a matching one
set incsearch                " Incremental search


" --- Tab settings ---
set tabstop=4
set shiftwidth=4
" Expand tabs for Python coding only (C/C++ in blender uses tabs)
" set expandtab
set smarttab


" ---- indenting ----
set autoindent " auto indent
set smartindent " smart indent
set ci " C/C++ indents
set cin " -


" --- Column/Row Stuff ---
set cul                      " Highlight the current line
:set number                  " Show Line Numbers
:set lines=40 columns=120    " Window Size
:set colorcolumn=120         " Right Margin


set scrolloff=3              " Scroll when cursor gets within 3 characters of top/bottom edge


" --- Extra Functionality Helpers ---
set autochdir                " cd into buffer editing

filetype plugin on
filetype indent on           " Indent

" auto-complete
set ofu=syntaxcomplete#Complete

Formatting Tools

AStyle

Command line formatter, http://astyle.sourceforge.net/astyle.html

This command is not exact but a close approximation of blenders style guide. noticeably, multi-line-if statements are formatted differently.

astyle --style=stroustrup \
       --pad-oper \
       --indent=tab \
       --indent-switches \
       --align-pointer=name \
       --break-closing-brackets \
       --unpad-paren \
       --pad-header \
        --recursive "*.c"

Uncrustify

The uncrustify configuration file us now included in Blender's tools repo:

Example use:

uncrustify -c ./source/tools/utils/uncrustify.cfg --no-backup --replace source/blender/blenlib/intern/path_util.c

This shell script runs uncrustify but removes minor whitespace cleanups which significantly reduces noise in the diffs.

uncrustify_clean.sh

./source/tools/utils/uncrustify_clean.sh source/blender/blenlib/intern/path_util.c