Last time this was brought up only one person complained, but it really is a serious problem and we need standards. Therefore I propose the following: * All source code files MUST use soft tabs at a tabstop of 4. No hard tabs are allowed. * All source code files SHOULD have the following as the first line of the file: # -*- Mode: Tcl; tab-width: 4; indent-tabs-mode: nil; c- basic-offset: 4 -*- vim:et:sw=4:ts=4:sts=4 This is a modeline that works for both emacs and vim. * 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 * Makefiles MUST use tabs as it is required by the syntax. Makefiles SHOULD use a tab stop of 4. * Makefiles MAY use a modeline. The following works for emacs and vim: # -*- Mode: Makefile; tab-width: 4; indent-tabs-mode: t -*- vim:noet:sw=4:ts=4 * All other files (documentation, etc) SHOULD use soft tabs at a tabstop of 4 if the document format allows. * All other files (documentation, etc) SHOULD NOT use a modeline as it is probably meant for human consumption. Does anybody have suggestions for any changes? If not, I recommend implementing this immediately. Every time I edit a file I will be converting it to this format and committing in a separate changeset to keep the svn history and diffs clean. I recommend everybody do this. -- Kevin Ballard http://kevin.sb.org eridius@macports.org http://www.tildesoft.com
Kevin Ballard wrote:
Last time this was brought up only one person complained, but it really is a serious problem and we need standards. Therefore I propose the following:
* All source code files MUST use soft tabs at a tabstop of 4. No hard tabs are allowed. * All source code files SHOULD have the following as the first line of the file: # -*- Mode: Tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:et:sw=4:ts=4:sts=4 This is a modeline that works for both emacs and vim. * 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 * Makefiles MUST use tabs as it is required by the syntax. Makefiles SHOULD use a tab stop of 4.
I suggest using a tab stop of 8. I never have modelines in my Makefile's so seeing a tab stop of 4 would look odd.
* Makefiles MAY use a modeline. The following works for emacs and vim: # -*- Mode: Makefile; tab-width: 4; indent-tabs-mode: t -*- vim:noet:sw=4:ts=4 * All other files (documentation, etc) SHOULD use soft tabs at a tabstop of 4 if the document format allows. * All other files (documentation, etc) SHOULD NOT use a modeline as it is probably meant for human consumption.
Does anybody have suggestions for any changes? If not, I recommend implementing this immediately. Every time I edit a file I will be converting it to this format and committing in a separate changeset to keep the svn history and diffs clean. I recommend everybody do this.
The thing we edit the most here is Portfile's, so I would suggest changing all the SHOULD's for Portfile's to MUST's, as that's where I'd like to see the most standardization. Regards, Blair -- Blair Zajac, Ph.D. <blair@orcaware.com> http://www.orcaware.com/training/
Citando Blair Zajac :
Kevin Ballard wrote: ...
* All source code files SHOULD have the following as the first line of the file: # -*- Mode: Tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:et:sw=4:ts=4:sts=4 This is a modeline that works for both emacs and vim. * 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
The thing we edit the most here is Portfile's, so I would suggest changing all the SHOULD's for Portfile's to MUST's, as that's where I'd like to see the most standardization.
For most Portfiles, the tcl mode is far from useful. From an error I have discovered that vim's tcsh syntax mode does interesting coloring of portfiles... Probably the best (for vim users at least) would be to create a vim syntax file for macports syntax (hence the modeline would become something like # vim:ft=macports). Emmanuel
On Sep 7, 2007, at 1:44 PM, Blair Zajac wrote:
Kevin Ballard wrote:
* Makefiles MUST use tabs as it is required by the syntax. Makefiles SHOULD use a tab stop of 4.
I suggest using a tab stop of 8. I never have modelines in my Makefile's so seeing a tab stop of 4 would look odd.
Fair enough. I'll copy my rules into a file in the repo, and I'll make the change there.
* Makefiles MAY use a modeline. The following works for emacs and vim: # -*- Mode: Makefile; tab-width: 4; indent-tabs-mode: t - *- vim:noet:sw=4:ts=4 * All other files (documentation, etc) SHOULD use soft tabs at a tabstop of 4 if the document format allows. * All other files (documentation, etc) SHOULD NOT use a modeline as it is probably meant for human consumption. Does anybody have suggestions for any changes? If not, I recommend implementing this immediately. Every time I edit a file I will be converting it to this format and committing in a separate changeset to keep the svn history and diffs clean. I recommend everybody do this.
The thing we edit the most here is Portfile's, so I would suggest changing all the SHOULD's for Portfile's to MUST's, as that's where I'd like to see the most standardization.
I would like to specify MUST but we have a lot more portfile maintainers then we have base committers and I'm somewhat hesitant to try and apply these rules to all Portfiles as a requirement when a surprisingly large number of Portfiles use 8-width hard tabs. If you think it's worth requiring these style rules for all further Portfile commits instead of simply strongly recommending them, please do make your argument. -- Kevin Ballard http://kevin.sb.org eridius@macports.org http://www.tildesoft.com
On Sep 7, 2007, at 1:31 PM, Kevin Ballard wrote:
Last time this was brought up only one person complained,
?? Every few months this comes up. There are a few people vocally in favor of one way or another to do things. I think most people don't care too much.
but it really is a serious problem and we need standards.
??
Therefore I propose the following:
[snip] My counter proposal is as follows: Whitespace rules inside of Portfiles are the maintainer's prerogative. Portfile authors should be consistent with their application of whitespace. When working on base/ code, the author should conform to the existing whitespace conventions of the code he/she is working on. These are the current, repeatedly agreed to, standards anyway. -- Daniel J. Luke +========================================================+ | *---------------- dluke@geeklair.net ----------------* | | *-------------- http://www.geeklair.net -------------* | +========================================================+ | Opinions expressed are mine and do not necessarily | | reflect the opinions of my employer. | +========================================================+
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512 Kevin Ballard wrote:
Last time this was brought up only one person complained, but it really is a serious problem and we need standards. Therefore I propose the following:
If I remember correctly, last time was decided every port maintainer can use his/her own rules. Even if there is no standard rule with this, I think we should give every maintainer/developer the freedom to choose this on his/her own.
* All source code files MUST use soft tabs at a tabstop of 4. No hard tabs are allowed. * All source code files SHOULD have the following as the first line of the file: # -*- Mode: Tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:et:sw=4:ts=4:sts=4 This is a modeline that works for both emacs and vim.
I really don't like this! Why add "useless" additional data to every file just because two editors work a bit better with this lines? There are many, many texteditors out there and why add additional information for only two of them (not counting the clones here). If emacs and vim users want to use standard settings for Portfiles then they can modify their editor settings. Please don't get me wrong, I really like vim (haven't worked with emacs yet), but I don't use it as main editor. And seeing this unnecessary information annoys me every time. Couldn't everybody just use his/her own settings? Without this additional line. By the way, the line is too long for 78 columns, so it would have to be split in two.
* 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 * Makefiles MUST use tabs as it is required by the syntax. Makefiles SHOULD use a tab stop of 4. * Makefiles MAY use a modeline. The following works for emacs and vim: # -*- Mode: Makefile; tab-width: 4; indent-tabs-mode: t -*- vim:noet:sw=4:ts=4 * All other files (documentation, etc) SHOULD use soft tabs at a tabstop of 4 if the document format allows. * All other files (documentation, etc) SHOULD NOT use a modeline as it is probably meant for human consumption.
All those changes will just end in a tabs/spaces war; some people like tabs more, others spaces. And then there is a wide range of tabs or soft tabs lengths, 8, 4, 2 ... the list goes on. I think we can't find an agreement here, so everybody should do it like he/she prefers. And because it's no difficulty in reading a file with other tab/space rules there shouldn't be a problem for anyone. Personally I prefer soft tab stops with the size of 2. Why is this better or worse then other rules?
Does anybody have suggestions for any changes? If not, I recommend implementing this immediately. Every time I edit a file I will be converting it to this format and committing in a separate changeset to keep the svn history and diffs clean. I recommend everybody do this.
I'm sorry if this mail sounded a bit rude, but I think we should all come to a consensus here, before we make quick decisions. If I update a Portfile I try not to modify the tab/space rules of this Portfile, so I just adapt. That shouldn't be a problem. And please wait for other maintainers/developers to comment on this before you make any changes to the portfiles. I think all should comment on this. Simon - -- + privacy is necessary + using http://gnupg.org + public key id: 0x6115F804EFB33229 -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.7 (Darwin) iD8DBQFG4Z4tYRX4BO+zMikRCmeMAKC88AapQ40lBUvp15SurefF0yTdCwCfekeh h7Sw/oAtTQ4G/oLnQ9bjPdE= =jHwI -----END PGP SIGNATURE-----
Simon Ruderich wrote:
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512
Kevin Ballard wrote:
Last time this was brought up only one person complained, but it really is a serious problem and we need standards. Therefore I propose the following:
If I remember correctly, last time was decided every port maintainer can use his/her own rules. Even if there is no standard rule with this, I think we should give every maintainer/developer the freedom to choose this on his/her own.
* All source code files MUST use soft tabs at a tabstop of 4. No hard tabs are allowed. * All source code files SHOULD have the following as the first line of the file: # -*- Mode: Tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:et:sw=4:ts=4:sts=4 This is a modeline that works for both emacs and vim.
I really don't like this! Why add "useless" additional data to every file just because two editors work a bit better with this lines? There are many, many texteditors out there and why add additional information for only two of them (not counting the clones here).
If emacs and vim users want to use standard settings for Portfiles then they can modify their editor settings.
Please don't get me wrong, I really like vim (haven't worked with emacs yet), but I don't use it as main editor. And seeing this unnecessary information annoys me every time. Couldn't everybody just use his/her own settings? Without this additional line.
By the way, the line is too long for 78 columns, so it would have to be split in two.
* 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 * Makefiles MUST use tabs as it is required by the syntax. Makefiles SHOULD use a tab stop of 4. * Makefiles MAY use a modeline. The following works for emacs and vim: # -*- Mode: Makefile; tab-width: 4; indent-tabs-mode: t -*- vim:noet:sw=4:ts=4 * All other files (documentation, etc) SHOULD use soft tabs at a tabstop of 4 if the document format allows. * All other files (documentation, etc) SHOULD NOT use a modeline as it is probably meant for human consumption.
All those changes will just end in a tabs/spaces war; some people like tabs more, others spaces. And then there is a wide range of tabs or soft tabs lengths, 8, 4, 2 ... the list goes on. I think we can't find an agreement here, so everybody should do it like he/she prefers. And because it's no difficulty in reading a file with other tab/space rules there shouldn't be a problem for anyone.
Why is it that most well known open-source projects have formatting rules that they abide to, even if some people personally don't like them. For example, the Subversion project uses the GNU C coding style, which I don't use in any of my personal code, but I use that style when I code on that project. They went through the war, had a vote, and choose and everybody abides by it. How come we can't do the same? I don't care what formatting rules we go with on Portfile's and would go with any standard, but I would much rather see consistency there. But I like consistency like that. Blair
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512 Blair Zajac wrote:
Why is it that most well known open-source projects have formatting rules that they abide to, even if some people personally don't like them. For example, the Subversion project uses the GNU C coding style, which I don't use in any of my personal code, but I use that style when I code on that project. They went through the war, had a vote, and choose and everybody abides by it. How come we can't do the same?
I don't care what formatting rules we go with on Portfile's and would go with any standard, but I would much rather see consistency there. But I like consistency like that.
Blair
I didn't said we shouldn't have a vote. I just said that I personally prefer it like it is now and that we first should make a decision (like a vote) and then start to change the Portfiles. But if we have a vote and then a standard, then I will follow this rules of course. That is what standards are for. Simon - -- + privacy is necessary + using http://gnupg.org + public key id: 0x6115F804EFB33229 -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.7 (Darwin) iD8DBQFG4aIMYRX4BO+zMikRCqPnAJ9sfP0qDIMeMbEs73GjzasDmXKnbACdHAZR 7aDCEwEvO021SubYzNqfePM= =ggtN -----END PGP SIGNATURE-----
* 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@macports.org http://www.tildesoft.com
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,
The majority of most portfiles consists of key value pair separated by some whitespace. Having tabs vs. soft tabs vs. spaces vs. whatever doesn't really effect the readability there. ... but we basically agree here, so I'll shut up about 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.
Do you mean me as the loud objector? I know at least one other person agreed with me in the list discussion ;-) We've had this discussion _many_ times in macports history.
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.
So to fix this, we can impose an arbitrary standard, or you could use diff -b ;-)
* 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.
macports has a set of friendly dictators who we elected to solve issues like this (portmgr). If they're convinced that this is the way to go, then that's probably good. It doesn't make sense for anyone who has commit on base/ to start dictating things to the rest of the volunteers, though.
No, I said it was necessary. Voting is good, but voting didn't work for whitespace,
because there wasn't a huge number of people who wanted to enforce strict whitespace last time? (ie, you didn't get consensus on the list ... probably because most people don't really care?)
and we needed rules.
We had rules, you're arguing that we needed _different_ rules (which is fine). -- Daniel J. Luke +========================================================+ | *---------------- dluke@geeklair.net ----------------* | | *-------------- http://www.geeklair.net -------------* | +========================================================+ | Opinions expressed are mine and do not necessarily | | reflect the opinions of my employer. | +========================================================+
-----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-----
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@macports.org http://www.tildesoft.com
_______________________________________________ macports-dev mailing list macports-dev@lists.macosforge.org http://lists.macosforge.org/mailman/listinfo/macports-dev
Juan Manuel Palacios <jmpp@macports.org> writes:
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.
# -*- Mode: Tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:et:sw=4:ts=4:sts=4
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.
I have not had time to follow the thread, and I've found out that "soft tabs" are tabs emulated with spaces. But though some are obvious, can someone explain what all the elements of the modeline do? Are any current ports using it? This needs to be documented. Mark
On Sep 7, 2007, at 7:09 PM, markd@macports.org wrote:
# -*- Mode: Tcl; tab-width: 4; indent-tabs-mode: nil; c-basic- offset: 4 -*- vim:et:sw=4:ts=4:sts=4
I have not had time to follow the thread, and I've found out that "soft tabs" are tabs emulated with spaces. But though some are obvious, can someone explain what all the elements of the modeline do? Are any current ports using it? This needs to be documented.
I constructed the modeline myself, so nothing's using it yet (except macports1.0/macports.tcl). There's 2 parts. The first is the -*- stuff -*-, which is for emacs. The second starts with vim: 1st part: Mode: Tcl sets the emacs mode to Tcl tab-width: 4 sets the tab width to 4 indent-tabs-mode: nil use soft tabs (yeah, the name is weird) c-basic-offset: 4 I don't know if this is necessary, but it declares the auto indent width as 4. 2nd part: vim: just the prefix that tells vim to use the rest of the line et Expand tabs, or use soft tabs sw=4 shift width = 4, used with the auto indentation mechanism ts=4 tabstop is 4 sts=4 soft tab stop is 4 -- Kevin Ballard http://kevin.sb.org eridius@macports.org http://www.tildesoft.com
participants (8)
-
Blair Zajac
-
Daniel J. Luke
-
David MacMahon
-
Emmanuel Hainry
-
Juan Manuel Palacios
-
Kevin Ballard
-
markd＠macports.org
-
Simon Ruderich