PLEASE READ: Whitespace rules

Fri Sep 7 14:15:27 PDT 2007

	I am unfortunately late to reply to this thread, even though it was  
me who encouraged Kevin to start it.

	Top posting to make a couple of general comments, I just wanted to  
state, officially and for the record (and yes, with my project  
manager hat on), that I am strongly supporting Kevin on this move  
because I strongly believe we do desperately need some coding rules  
and conventions *every* one must one abide by, just like many other  
open source projects do.

	It pleases me to realize that MacPorts has grown to the point of  
requiring such formalities, because every project in its inception is  
small enough to afford a small group of developers friendly agreeing  
on how to write down their code. But anything even a bit bigger than  
that quickly becomes disorganized and unmanageable if no explicit  
rules are laid out, up to the point of reflecting the mess base/ code  
currently is. There simply is no consistency what-so-ever and no  
"surrounding standard" to respect and stick to any longer.

	Therefore we have to start imposing one and asking everyone to abide  
by it and respect it, without too much argument and discussion  
because things like these are the perfect candidates for the tastiest  
bikesheds!

	I asked Kevin to start this thread, and I accept that as my mistake  
because it should have been me or anyone else in portmgr the one  
doing it... reason why we got elected to that position. Apologizing  
for having created such confusion, I would now like to rectify it by  
explaining that what Kevin originally wrote (and what he consequently  
wrote in this mail below) is not only something we had previously  
discussed and agreed on, but also the most common and standard coding  
conventions out there used in many large open source projects;  
there's simply not much new about what's being asked here.

	Of the things that are particular to MacPorts, our Portfiles:

  * Portfiles SHOULD use soft tabs at a tabstop of 4, but  
implementation of this is left up to the discretion of the maintainer.
  * Portfiles SHOULD use the given modeline.

	We could add here that the standard *MUST* be met for nomaintainer  
ports (since anyone is allowed to jump in and edit, resulting in the  
same mix that we want to fix) and encouraged to the sole or main  
maintainer(s) (in the case of open maintainership) when the port has  
a proper father/mother. But needless to say, main maintainers are  
allowed to follow their own conventions if the suggested standard  
does not please them, and ask contributors to respect their choices  
in the case of open maintainership. Please feel free to bring up any  
polishing you feel might is appropriate to other MacPorts specific  
aspects of our code base.

	So, hopefully having cleared up any confusion, lets please move  
beyond the bikeshed and onto applying these very simple principles of  
good coding citizenship. You should of course feel free to reply if  
you have qualms about what may seem like an imposition, but please  
make that a well founded argument in favor of an alternative if you  
have one, rather than a simple "I don't like it!"

	Lastly, don't retort to Kevin because you might feel this is a free  
will imposition on his side. As said earlier, I personally encouraged  
him to write about something we had already discussed and agreed on,  
and it was my mistake to not bring it up to the list's attention  
myself. So in a nutshell, this is indeed a portmgr move, unless mww  
and jberry explicitly contradict me, which they can... but since they  
have before stated they don't care enough about it to have an  
opinion... or am I mistaken?

	Regards to all and thank you for your attention and understanding,...

-jmpp

On Sep 7, 2007, at 3:44 PM, Kevin Ballard wrote:

> * Why have rules for Portfiles? Isn't that the maintainer's  
> prerogative?
>
> Yes it is, which is why I marked those rules as SHOULD rather than  
> MUST. Having consistent rules for Portfiles aids reading of  
> Portfiles, especially if the Portfile is marked openmaintainer@ as  
> those are edited by multiple people. But if a maintainer prefers  
> their own style, they may use it.
>
> * Last time we decided that developers working on base/ code should  
> conform to the surrounding style.
>
> No we didn't. Last time one person loudly objected, and the  
> discussion eventually died without coming to any consensus.  
> However, having consistent style rules is very important. As it  
> stands, every single time I edit base/ code I have to worry about  
> my tab settings and I frequently have to go back and re-tab things  
> to conform to the surrounding style simply to avoid extraneous  
> lines on the diff. This is especially bad when the surrounding  
> style itself isn't consistent. Additionally, some code has tabstops  
> of width 8 and most has tabstops of width 4, so I can't even read  
> some code without changing my own tab width. There's a reason most  
> open source projects have style rules.
>
> * Why add modelines to files? I don't use vim/emacs so they're  
> useless noise.
>
> vim and emacs are the two most common command-line editors, and  
> they (well, emacs) are also responsible for the 8-width tabs  
> scattered throughout the code as this is what emacs and possibly  
> vim (I don't remember anymore) defaults to. Since we have the power  
> to explicitly mark our files as wanting certain spacing rules in  
> vim and emacs, we should. If other popular editors supported  
> modelines then we'd consider adding rules for those, but I'm not  
> aware of any other popular editor which supports modelines. As for  
> it being useless noise, I disagree. All our files are already  
> prefixed with license text, so adding one more line of comment  
> won't make any difference. If it hadn't been pointed out you  
> probably wouldn't have noticed.
>
> * The modeline is greater than 78 characters, it should be split up.
>
> True, it is larger than 78 characters, which is the traditional  
> line length to accommodate terminals. But our source isn't wrapped  
> at 78 characters. If we ever establish a 78 character line length  
> for our source, then the modeline would have to be wrapped. In that  
> case we would split the vim modeline off from the emacs modeline.
>
> * I like hard tabs, why can't I use those? Or: I prefer soft tabs  
> of size 2.
>
> We absolutely need a consistent standard. The source is a complete  
> mess without one. Unfortunately, there's no single standard that  
> will please everybody, so we need to go with a common compromise.  
> Soft tabs were chosen in order to make it easier to read source  
> code in any editor. When hard tabs are used, the source looks  
> different for people who have tab size set to different lengths.  
> This is a real problem when tabs are mixed with spaces (as is  
> common). You can open a source file and see perfect indentation,  
> and I can open a source file and see nested scopes indented less  
> than their parents. Soft tabs ensures everybody sees the exact same  
> indentation. As for a tab size of 4, that was chosen as it's the  
> most common tab size for source code, and a standard is needed for  
> this as well to ensure code consistency when editing. A size of 2  
> would work just as well if everybody agreed to it, but since 4 is  
> more common, 4 is what was chosen.
>
> * Shouldn't we have a vote on this?
>
> No we shouldn't. Every time we've tried to come to a consensus, the  
> issue has stalled. Therefore I'm going with a dictatorial approach  
> on this. The only way to get a good standard is to force it on  
> everybody, and we desperately need one.
>
> * What about style rules for braces, etc?
>
> We probably should write down rules for those, but there isn't  
> really a need at this point. Tcl disallows the statement-newline- 
> brace syntax favored by some C coders, and that tends to be the  
> biggest divide among coders on style rules. There may be other  
> points of contention, but they don't affect people anywhere nearly  
> as much as the whitespace rules. If someone wants to write up a  
> style document for the non-whitespace rules, please do send it to  
> the list and we'll have a vote.
>
> * Wait, didn't you just say the dictatorial approach was better?
>
> No, I said it was necessary. Voting is good, but voting didn't work  
> for whitespace, and we needed rules. But we aren't in desperate  
> need of other style rules, so voting is fine there.
>
> * I have another question/complaint.
>
> Please send it to me and I'll address it in another email.
>
> -Kevin Ballard
>
> -- 
> Kevin Ballard
> http://kevin.sb.org
> eridius at macports.org
> http://www.tildesoft.com
>
>
> _______________________________________________
> macports-dev mailing list
> macports-dev at lists.macosforge.org
> http://lists.macosforge.org/mailman/listinfo/macports-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/macports-dev/attachments/20070907/48f5f8f0/attachment.html