Let's end the formatting mess

[Milian Wolff]

On Wednesday 09 November 2011 02:44:20 David Nolden wrote:
> In the last days I've added a script and matching configurations to
> KDevelop which allows defining shared fine-grained formatting scripts
> right within the source directory structure.
> 
> "format_sources" files can be placed in the source directory, which
> assign formatting-script calls to wildcard patterns. The
> "kdev_format_source.sh" script uses these files to match
> file-patterns, and format sources with the according formatting
> command.
> 
> I've added a predefined config for "kdev_format_sources.sh" in the
> custom-script plugin, which means that everything required to use
> these formatting files is activating that config, and making sure that
> the underlying formatting-scripts (eg. uncrustify) are functional.
> 
> Uncrustify is a very powerful source-formatter with much more options
> than astyle, and performing much more extensive reformatting. I've
> found a configuration which mostly resembles the coding-style in
> kdevplatform/language and kdevelop/languages/cpp, and attached this
> configuration to all the C++ files in these directories using
> "format_sources" files. Soon I will reformat all the files, and from
> then on, we can easily enforce a consistent coding style there.
> 
> As a next step, I think we should do the same for all of KDevelop and
> KDevplatform, to finally get rid the inconsistent formatting all
> around. The question is, if we can find an uncrustify config which
> satisfies all of us. Personally I would like to use the 2-spaces
> indent style used in kdevplatform/language and kdevelop/languages/cpp
> in all of KDevelop, because 2-spaces is more economical regarding
> screen real-estate.

Yes, finally! I totally agree in that we need a consistent style everywhere. 
Personally I like the two spaces as well, but wouldn't care too much about 
four spaces either.

But: The "real" next step before actually reformatting everything is to find a 
style we all follow. As we are a KDE project, I personally vote for: 
http://techbase.kde.org/Policies/Kdelibs_Coding_Style

1) This makes it easy for people to contribute to KDE, as they just need to 
remember one style. And many developers are already acquainted with that 
style.

2) It is already documented, we don't need to sit down and define what want 
others to do.

3) It is "proven", i.e. many people work with it and it works well for them.

4) It is near to the Qt-coding style, i.e. see again 1).

5) There is even an astyle config for it.

The biggest downside I see right now is that most of us will have to get 
acquainted with some parts of this style, most importantly the "correct" 
placement of &* (i.e. next to the name and not to the typename as we are used 
to in KDevelop).

Which brings me to the second part: Having a reformat-all guideline is nice 
and useful. But to actually enforce this we could need two things:

a) proper in-editor "on-the-fly" formatting. This is actually a long standing 
feature request, and a very important one.

b) a pre-commit hook that compares checked-in-file VS reformatted checked-in-
file. If they differ, it rejects the file. This would of course require work from 
our beloved KDE BOFHs which are always pretty busy. Most probably one of us 
would need to sit down and get this hook implemented. I reason this would be 
very useful for other projects as well.

Both are imo important but could / should be done after we agreed on a proper 
style. If we start to enforce a proper style - even if only manually - for new 
code, we won't have much work later. But it still won't prevent our codebase 
from getting messy again. The two points above, esp. the hook, are required to 
get this done.

> And another thing: What is the sense of all the kate modelines around?
> It seems like kate inherits these options just fine from the source
> files, so the modelines aren't required.

Kate has no ability to "guess" the code style from a file, the modelines are 
required. But the preferred way is to put them into a project file (search for 
.kateconfig).

-- 
Milian Wolff
mail at milianw.de
http://milianw.de
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kdevelop-devel/attachments/20111110/d4ce8777/attachment.sig>