10.5.3 Code formatting

Formatting tools

For C++ files, standard GNU coding style is used. You can reformat a file according to this style using the clang-format tool.

clang-format -i filename

The version of clang-format currently being used is version 14.0.

Bindings for clang-format are available for many editors, including Emacs and Vim.

clang-format can also be run on all files at once, but this is normally only done infrequently, more specifically before branching the next stable release.

clang-format -i $(git ls-files "*.cc" "*.hh" "*.icc" "*.tcc")

Similarly, we have a script that reformats Scheme files.

scripts/auxiliar/fixscm.sh filename

To run it on all files, use

scripts/auxiliar/fixscm.sh $(git ls-files "*.scm")

This script drives Emacs behind the scenes, so Emacs users will get the right behavior out-of-the-box.

For Python code, use autopep8 with the following settings:

autopep8 -ia --ignore=E402 file.py

However, currently files under release/binaries/ are formatted with a different tool, black.

Vim-specific configuration

For C++ formatting, although using a plugin that provides a binding for clang-format allows you to fix indentation automatically, it does not produce correct indentation as you type. You can, however, adjust your Vim configuration to come close. These settings were adapted from the GNU GCC Wiki. Save the following in ‘~/.vim/after/ftplugin/cpp.vim’:

setlocal cindent
setlocal cinoptions=>4,n-2,{2,^-2,:2,=2,g0,h2,p5,t0,+2,(0,u0,w1,m1
setlocal shiftwidth=2
setlocal softtabstop=2
setlocal textwidth=79
setlocal fo-=ro fo+=cql
" use spaces instead of tabs
setlocal expandtab
" remove trailing whitespace on write
autocmd BufWritePre * :%s/\s\+$//e

For Scheme code, you can use these settings in ‘~/.vim/after/syntax/scheme.vim’:

" Additional Guile-specific 'forms'
syn keyword schemeSyntax define-public define*-public
syn keyword schemeSyntax define* lambda* let-keywords*
syn keyword schemeSyntax defmacro defmacro* define-macro
syn keyword schemeSyntax defmacro-public defmacro*-public
syn keyword schemeSyntax use-modules define-module
syn keyword schemeSyntax define-method define-class

" Additional LilyPond-specific 'forms'
syn keyword schemeSyntax define-markup-command define-markup-list-command
syn keyword schemeSyntax define-music-function def-grace-function

" All of the above should influence indenting too
setlocal lw+=define-public,define*-public
setlocal lw+=define*,lambda*,let-keywords*
setlocal lw+=defmacro,defmacro*,define-macro
setlocal lw+=defmacro-public,defmacro*-public
setlocal lw+=use-modules,define-module
setlocal lw+=define-method,define-class
setlocal lw+=define-markup-command,define-markup-list-command
setlocal lw+=define-music-function,def-grace-function

" These forms should not influence indenting
setlocal lw-=if
setlocal lw-=set!

" Try to highlight all ly: procedures
syn match schemeFunc "ly:[^) ]\+"

Files can be reindented automatically by highlighting the lines to be indented in visual mode (use V to enter visual mode) and pressing =, or a single line correctly indented in normal mode by pressing ==.

For documentation work on texinfo files, identify the file extensions used as texinfo files in your ‘.vim/filetype.vim’:

if exists("did_load_filetypes")
augroup filetypedetect
  au! BufRead,BufNewFile *.itely setfiletype texinfo
  au! BufRead,BufNewFile *.itexi setfiletype texinfo
  au! BufRead,BufNewFile *.tely  setfiletype texinfo
augroup END

and add these settings in ‘.vim/after/ftplugin/texinfo.vim’:

setlocal expandtab
setlocal shiftwidth=2
setlocal textwidth=66

LilyPond — Contributor’s Guide v2.23.82 (development-branch).