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

[Graham Percival]

Updated proposal:
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.
    * for now, this style will not be enforced. It is not cause
      for concern if patches which do not follow the formatting
      done by fixcc.py are pushed. From time to time, Graham will
      run the formatter on the entire code base, and commit the
      resulting changes.

      In a few months, we will tighten up this policy item (with
        some sort of automatic processing), but that is outside
        the scope of this policy item and is a matter for later
        discussion.

    * after the proposal is accepted, we will leave some time for
      existing patches to be accepted and pushed. 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. This refers both to tabs for indentation,
and also tabs inside strings (those should use \t instead).

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


** GNU code

LilyPond is a GNU project, so it makes sense to follow the GNU
coding standards. These standards state:

    We don’t think of these recommendations as requirements,
because it causes no problems for users if two different programs
have different formatting styles.

    But whatever style you use, please use it consistently, since
a mixture of styles within one program tends to look ugly. If you
are contributing changes to an existing program, please follow the
style of that program. 

(http://www.gnu.org/prep/standards/html_node/Formatting.html)

With that in mind, we do not think that we must blindly follow the
formatting given by the currrent version of Emacs.


** Practical considerations

Not everybody has emacs installed, and the C++ formatting varies
between versions. On lilydev, installing emacs requires a 23.9 MB
download (will use 73.6 MB disk space when uncompressed), while
downloading astyle 2.02 requires 150.8 KB (I don’t know how much
that is uncompressed).

lilydev currently does not have either emacs nor astyle installed,
but either can be added easily in the next version.


** 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