incubator-lucy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marvin Humphrey <mar...@rectangular.com>
Subject [lucy-dev] C code formatter
Date Sat, 09 Apr 2011 03:43:21 GMT
Greets,

Automatic code formatters present significant benefits for collaborative
projects.

  1. Consistency of style across the code base is worth making local
     sacrifices for.
  2. Automatic code formatters settle stylistic disagreements diplomatically:
     it's no longer a human committer sitting in judgment of your patch's
     style, since all changes can be blamed on the automatic code formatter.

We already use an automatic code formatter for Lucy's Perl code: Perltidy with
settings basically derived from what Damian Conway advocates in his book,
"Perl Best Practices" and which are in conformance with the Perl core
documentation for "perlstyle".  For our C code, though, we don't have an
automated process in place.  

I'd like to propose that we adopt an automatic code formatter for Lucy's C
code -- specifically 'astyle' a.k.a. "Artistic Style".

    http://astyle.sourceforge.net/

When Dave Balmain and I worked up the Lucy style guide back in 2006, the most
obvious option for C code formatting was the Unix utility "indent".  However,
indent has a lot of problems.  It's not consistent across platforms -- the
version that comes with OS X can't even handle double-slash comments.  It's
also very invasive -- it's hard to persuade indent to leave your manual
adjustments alone, particularly manually lined-up assignment statements.  So
ultimately, we chose to issue guidelines only rather than enforce them with
indent.

Surveying the landscape today, it seems like astyle has emerged as a leader.
It is portable, popular, and stable.  Additionally, it is less invasive than
indent.  Uncrustify is another possibility
(<http://uncrustify.sourceforge.net/>), but it seems less refined and mature
than astyle.  From "uncrustify --help": 

    There are currently 395 options and minimal documentation.
    Try UniversalIndentGUI and good luck.

After playing around for a while, I've come up with an astylerc file (contents
below my sig) which is as close as possible to what's in the Lucy code base
already.  It will be necessary to make a few minor manual tweaks when applying
it, but the overall appearance of the code base will not change much before
and after.  The biggest difference is that astyle will line up arguments with
parens more aggressively -- which I think is a positive change:

     return PolyReader_init(self, schema, folder, snapshot, manager,
-        sub_readers);
+                           sub_readers);

Aside from that, it mostly erases some personal idiosyncrasies of mine -- for
example, it uses a more traditional alignment within multi-line conditionals.

Note that applying this astylerc won't place us precisely in conformance with
<http://wiki.apache.org/lucy/LucyStyleGuide>, which defers to the Apache HTTPD
style guide -- but then, we aren't in conformance now.  I think we should
consider removing that HTTPD reference and defer to the astylerc instead, so
that we are actually following our own rules.

Marvin Humphrey

#---------------------------------------------------------------------

# Disallow tabs.
--convert-tabs

# K&R-style brackets.
--brackets=linux

# Indent switches and case statements.
--indent-switches
--indent-cases

# Indent backslash continuations within a preprocessor directive.
--indent-preprocessor

# Vertically align subsections of multi-part conditionals.
--min-conditional-indent=0

# Force space around operators, i.e. "foo = 7" not "foo=7".
--pad-oper

# Don't cuddle elses.
--break-elseifs
--break-closing-brackets

# Allow statements to occupy one line, particularly conditional statements:
#
#    if (foo) do_stuff();
#
--keep-one-line-statements

# Allow single-line blocks:
#
# int
# Foo_get_thing(Foo *self)
# { return self->thing; }
#
--keep-one-line-blocks

# Force space between if/when/while and opening paren.
--pad-header

# Tighten parens around their contents.
--unpad-paren


Mime
View raw message