PLEASE READ: Whitespace rules

[Simon Ruderich]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Hi Kevin,

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.

I think _if_ we add strict rules then they should be a must. So
everybody who modifies a port should also update the port to this rules
(in a different commit). This would make it easy for everybody to read
and edit the files.

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

Then I'm sorry. I thought I remembered it that way.

My comments were only pointed at Portfiles. For the macports tcl source
files style rules are really a very good idea.
But as Portfiles are normally not so much code, I think the need for
strict rules are not so necessary there.

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

I had noticed it before and I never liked it. But that's just my opinion.

I we set up any rules about using such a line, then I will follow them
of course.

> * 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 can't say anything about the tcl source files, but as most ports are
wrapped around 78 characters we should split the line in Portfiles (if
we use it).

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

I also prefer soft tabs and they should be part of the (potential)
standard. But rather on defining a standard on soft tabs, we should
define it how a Portfile should look like.

My preference is the following Portfile (just an example):

# $Id$

PortSystem 1.0

name                NAME
version             VERSION
categories          CATEGORIES
maintainers
description         DESCRIPTION
long_description    $description
homepage            HOMEPAGE
platforms           darwin
master_sites        MASTER_SITES

checksums           md5 MD5SUM \
                    sha1 SHA1SUM \
                    rmd160 RMD160SUM

depends_lib         port:abc \
                    port:def \
                    ...

The main things to point out in a standard Portfile is the indentation
and the order of the variables. I'm not sure if a strict order of
variables/indentations is a good thing, but I like the idea. And such a
strict rule would really make editing/viewing Portfiles simpler.

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

I don't like dictatorial approaches, especially not in open source
projects. Of course someone has to make a decision (and I'm fine if this
one is you), but before we do it, we should at least discuss it to find
out what other users like.

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

I can't say anything about such rules, because I'm no Tcl developer. But
again, such rules would be good.

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

Again, I think we should first collect comments from others and then
you/or anybody else can make a final decision. Doing it just alone
without the community just doesn't look right.

> * I have another question/complaint.
> 
> Please send it to me and I'll address it in another email.

We (as many developers/maintainers as possible) should work together to
get a good standard rule for everybody. This includes a discussion and
maybe a vote. But I think everybody has the right to include his/her
opinions on this point and they should be integrated (if possible) in
your proposal. After that we/you can be made a mandatory rule which
everybody should/has to follow.

> -Kevin Ballard

Simon
- --
+ privacy is necessary
+ using http://gnupg.org
+ public key id: 0x6115F804EFB33229
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (Darwin)

iD8DBQFG4bS6YRX4BO+zMikRCjP5AKDbo66M7JkpozYLNCDLVhMEnZOKSgCfSTp8
oHd/TyoGcusiIZVoRdQjIZg=
=EDLL
-----END PGP SIGNATURE-----