Re: Code formatter

[Graham Percival]

(sorry if it's a duplicate; email problems)

On Fri, Nov 13, 2009 at 10:44:54AM -0500, Chris Snyder wrote:
> Graham Percival wrote:
>> 1) running astyle will change lines of code.  This makes the
>> history harder to look at... if we want to know who wrote a
>> particular line (say, "there seems to be a bug here; hey Joe, why
>> did you write "if (x = 3)" ?"), then it will appear that *you*
>> were the last person to change that line of code.  Even if all you
>> did was run astyle on it.
>
> That seems to me to be unavoidable - or at least not worth the cost  
> (investigating whitespace-aware diff tools, etc.) of avoiding it. Since  
> the commit message would be "Automated formatting cleanup" we would just  
> go to the previous commit in the tree (looking back on the Frogs list  
> discussion, I see that you suggested exactly that).

Yes... but it should only be done ONCE.  We should only run this
when we're certain that we have the right tool.

If somebody thinks that astyle is the right tool, then that person
can make an argument in favor of it.  Give us the info -- what
does astyle do differently?

>> 2) many programmers view code style in a highly personal,
>> quasi-religious manner.
> ...
>> ...Han-Wen and Jan have different views...
>
> If the standard isn't even completely defined then how could the job of  
> code janitor be given to an inexperienced Frog? It seems to me that no  
> one can solve this problem until an official LilyPond coding standard is  
> fully set in stone. In the meantime, newbies are left wondering what  
> code style they should adhere to (perhaps having to predict which dev  
> will be looking at a particular patch).

That's why I think this is the 3rd most important task to help new
developers.

I'm not saying that astyle *isn't* the best.  I'm saying that you
need to make an argument.  Don't just say "hey, I found this tool
on teh internets, somebody run it on the source tree for me!".

- what does astyle do by default?
- what options does astyle have?
- which set of options in astyle produces the smallest possible
diff with our existing code?
(don't answer the questions on the list -- go investigate them)


I did this task with Marsyas (another open-source project, albeit
oriented on audio analysis+synthesis rather than music notation).
I know what I'm talking about.  There's both technical and
diplomatic portions to this task.

(as it happens, it was a partial victory.  I managed to convince
everybody else that astyle with a custom .astylerc file was the
best choice... but they refused to let me run it on all the source
files, for the history reasons.  The final verdict was "use this
for anything new, otherwise keep your grubby paws off my source
code")

> I'm going to "come out of the closet" here, in a manner - I'm primarily  
> a Java programmer. I don't think I can count on both hands the number of  
> personal formatting preferences (not to mention an intense dislike of  
> C++ - but I'm not about to touch *that* dead horse) I've suspended in  
> order to contribute. I'm not complaining about this - as a newcomer,  
> it's my duty to adhere to established standards - but I'd like to know  
> what the standards are.

Unfortunately, it's not really set in stone.  Yes, that makes your
job harder.

*shrug*

if it was a 10-minute task, I would have done it already.

>> Sometimes, the automatic tool will just make existing
>> badly-formatted code meet our own standards.  In other cases, it
>> *will* change the standards.  Some of us won't care; others will
>> care deeply.
>
> I know I'm not in a position to credibly admonish those that have put  
> countless hours into what's essentially a labor of love, but it seems to  
> me that these personal holy wars often get in the way of real  
> productivity (the amount of time you've expended responding to me, for  
> instance). It looks to me that 99% of the coding style is agreed upon -  
> is the 1% really worth all of this frustration?

I'm not asking the impossible.  Do the steps I outline above.
Then pick one particular file... ideally a file that shows all the
types of changes that the astyle+astylerc will produce.

Send the diff here.  Or maybe to the Frog list first.  :)

Give a rationale for all the changes.  It could be as simple as
"umm, astyle actually conforms to the GNU standard, whereas the
current source file doesn't".  Or it might be something like "it
conforms to GNU with the extra modifications made by fixcc.py."
Or maybe even something like "it doesn't match GNU *or* fixcc.py,
but in this email here, Jan said that we should do XYZ, and
Han-Wen said `whatever, I don't care any more'".

I don't think the latter case will apply.  But it might!


Again, it's not impossible.  But you need to do the homework
before we can start discussing it seriously.  I repeat my claim of
10-20 hours.  Probably 4 hours playing with astyle (and/or other
tools) and experimenting with different options, and 6 hours of
discussion + reading old emails + discussion.  And doubling it
just because I double all estimates.  Oh, those estimates include
scheme stuff as well.

I know that you're thinking "this is ridiculous", but unless
somebody does it, newbies will continue to face this difficulty.
This job won't get done by itself.

Cheers,
- Graham