GOP-PROP 3 - C++ formatting (probable decision)

[Graham Percival]

http://lilypond.org/~graham/gop/gop_3.html

** Proposal summary

Speaking academically, C++ code style is a "solved problem". Let’s
pick one of the existing solutions, and let a computer deal with
this. Humans should not waste their time, energy, and creativity
manually adding tabs or spaces to source code.

I propose that we use a modified fixcc.py using astyle internally.

    * the final script will be run blindly on the lilypond source
      code. We will accept whatever formatting the final version
      of this script produces, with no manual tweaking.
    * patches which have been run through this tool will not be
      rejected for style reasons. Any code formatting “desires”
      which are not enforced by fixcc.py will not be considered
      grounds for rejecting a patch.
    * after the proposal is accepted, we will leave over two weeks
      for existing patches to be accepted. The script will be run
      on the source code on 2011 August 01. 

We will take the fixcc+astyle from here:

http://codereview.appspot.com/4662074/

(just the fixcc.py and maybe some test files; we will not make any
changes to .cc or .hh files until 2011 August 01)


** Rationale

New contributors sometimes struggle to follow our indentation and
code style – this is especially difficult when parts of our
existing source code doesn’t have a consistent style. This is
problematic... we want new contributors to be struggling with the
lilypond architecture, not playing games in their text editors!

we’ve lost time, energy, and contributors because of this. Two bad
examples: (the second one hopefully hasn’t lost us a contributor –
but her patch was delayed by three weeks because of indentation
issues, and that can’t be very encouraging)

http://codereview.appspot.com/1724041/
http://codereview.appspot.com/4490045/

This is also the worst “administrative” time-wasters in recent
LilyPond history; we’ve had numerous discussions without actually
resolving anything. Previous discussions on tabs v. spaces include
the following:

http://thread.gmane.org/gmane.comp.gnu.lilypond.devel/22691
http://lists.gnu.org/archive/html/lilypond-devel/2009-04/msg00076.html


** Eliminate tabs

I’m going to make the bold step of assuming that we will eliminate
tabs in all C++ files. I personally like the idea of tabs, but
from an examination of source code styles (both official and
unofficial) in various projects, I must admit that this ship has
sailed. Too many programs/editors don’t support tabs. Too many
people find them confusing. Too many cut&paste jobs from html
results in spaces instead of tabs.
        
http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Spaces_vs._Tabs
http://www.rosegardenmusic.com/wiki/dev:coding_style
http://techbase.kde.org/Policies/Kdelibs_Coding_Style


** Implementation notes

Some amount of mess is unavoidable, but I believe it can be
mitigated.

lilydev needs to have whatever tool we end up choosing. Patches
will break, unless somebody applies the patch to the un-indented
source code, then run the indentation tool, then make a new patch,
etc. Massive confusion.

Hopefully we can get most of the existing patches merged before
2011 Aug 01. It’s not the end of the world if we need to give
manual attention to a few patches right after the change-over,
though.

Future: we may want to consider adding a git hook to call whatever
indentation script before any commit. This will not be implented
as part of this proposal, though.

We can avoid some of this pollution in git history by ignoring
whitespaces changes:
        
git diff -w



Cheers,
- Graham