Hi everybody,
I'd love to ask you if we have some coding style guidelines. If we don't I'd like to propose creating such thing and start to enforce it in a review process.
some of the guidelines ideas are: * 2 spaces over tabs * fuzzy (i.e. non-strict limit) for 80 chars per line (and yes - 120 chars are way too much) * using instance variables only when you *really* need it * 'do...end' and curly braces conventions (?) * CamelCaseOnlyForClassNames
any ideas?
- maros
On 04/26/12, Maros Zatko wrote:
Hi everybody,
I'd love to ask you if we have some coding style guidelines. If we don't I'd like to propose creating such thing and start to enforce it in a review process.
Actually it's not bad idea to have some coding/style guidelines in place. If all people adopt them and use them, then the resulting project codebase will look more consistent.
I want to propose this: https://github.com/bbatsov/ruby-style-guide for the general discussion :-)
-- Mich
some of the guidelines ideas are:
- 2 spaces over tabs
- fuzzy (i.e. non-strict limit) for 80 chars per line (and yes - 120 chars
are way too much)
- using instance variables only when you *really* need it
- 'do...end' and curly braces conventions (?)
- CamelCaseOnlyForClassNames
any ideas?
- maros
On Thu, Apr 26, 2012 at 06:02:00PM +0200, Michal Fojtik wrote:
On 04/26/12, Maros Zatko wrote:
Hi everybody,
I'd love to ask you if we have some coding style guidelines. If we don't I'd like to propose creating such thing and start to enforce it in a review process.
Actually it's not bad idea to have some coding/style guidelines in place. If all people adopt them and use them, then the resulting project codebase will look more consistent.
I want to propose this: https://github.com/bbatsov/ruby-style-guide for the general discussion :-)
Yes! That's the resource I was thinking of.
This reminds me of one thing I've seen us do inconsistently -- parenthesis for arguments where they're not strictly required.
For example, I prefer: user.update_attribute(:foo, 'bar')
But this is also totally valid: user.update_attribute :foo, 'bar'
It seems that some people try to always use the parens, some try to never use them, and some (AFAICT) prefer to use them only when there is more than one argument. The linked style guide suggests using them when they are part of an internal DSL or considered "keywords" or accessor methods, but all other method invocations should use parens. I don't feel too strongly, except that consistency is nice.
-- Matt
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
On 04/26/2012 10:16 AM, Matt Wagner wrote:
On Thu, Apr 26, 2012 at 06:02:00PM +0200, Michal Fojtik wrote:
On 04/26/12, Maros Zatko wrote: I want to propose this: https://github.com/bbatsov/ruby-style-guide for the general discussion :-)
Yes! That's the resource I was thinking of.
This reminds me of one thing I've seen us do inconsistently -- parenthesis for arguments where they're not strictly required.
For example, I prefer: user.update_attribute(:foo, 'bar')
But this is also totally valid: user.update_attribute :foo, 'bar'
It seems that some people try to always use the parens, some try to never use them, and some (AFAICT) prefer to use them only when there is more than one argument. The linked style guide suggests using them when they are part of an internal DSL or considered "keywords" or accessor methods, but all other method invocations should use parens. I don't feel too strongly, except that consistency is nice.
-- Matt
Speaking as someone who has to read this code (and is not super familiar with it) I would greatly appreciate anything that results in consistency/making my life easier =).
- -- Kurt Seifried Red Hat Security Response Team (SRT) PGP: 0x5E267993 A90B F995 7350 148F 66BF 7554 160D 4553 5E26 7993
On Thu, Apr 26, 2012 at 05:25:04PM +0200, Maros Zatko wrote:
Hi everybody,
I'd love to ask you if we have some coding style guidelines. If we don't I'd like to propose creating such thing and start to enforce it in a review process.
To my knowledge, all we really have is a notion of what others have done in the past. But I think it would be a good idea to start to write those things up on a wiki page.
some of the guidelines ideas are:
- 2 spaces over tabs
- fuzzy (i.e. non-strict limit) for 80 chars per line (and yes - 120
chars are way too much)
I'm not sure I completely agree with this one. There is certainly some point at which lines are too long, but I'm not sure 80 characters is it. It feels like a carryover from VT100 days, and I can view considerably more than 80 characters on even my 13" laptop at home.
What I'd rather see is a guideline like, "Try to keep your lines to 120 characters at most. If you cannot easily refactor code to use shorter lines, here is the recommended best practice of spanning multiple lines...."
- using instance variables only when you *really* need it
- 'do...end' and curly braces conventions (?)
- CamelCaseOnlyForClassNames
Some of these are standard Ruby conventions, e.g., using curly braces only for one-liners, vs. do..end for multi-line blocks, or CamelCaseOnlyForClassNames. I seem to recall having read a really great overview of many common Ruby conventions in the past, but, of course, I cannot find it now.
Personally, I'd rather our list was more a set of "Best Practices" or "Preferred Conventions" to help us be more consistent, versus a set of mandatory rules. Some larger projects (which shall remain nameless) seem to irritate a lot of people by having rigid requirements that presumably started off as well-intentioned guidelines to help keep things consistent/structured, but turned into a set of hurdles that don't always have any benefit.
Do you want to take a stab at throwing some of these up the wiki, and others can add more (or object to some of them)? I have a few more I can think of adding.
-- Matt
On Thu, Apr 26, 2012 at 12:04:06PM -0400, Matt Wagner wrote:
On Thu, Apr 26, 2012 at 05:25:04PM +0200, Maros Zatko wrote:
Hi everybody,
I'd love to ask you if we have some coding style guidelines. If we don't I'd like to propose creating such thing and start to enforce it in a review process.
To my knowledge, all we really have is a notion of what others have done in the past. But I think it would be a good idea to start to write those things up on a wiki page.
some of the guidelines ideas are:
- 2 spaces over tabs
- fuzzy (i.e. non-strict limit) for 80 chars per line (and yes - 120
chars are way too much)
I'm not sure I completely agree with this one. There is certainly some point at which lines are too long, but I'm not sure 80 characters is it. It feels like a carryover from VT100 days, and I can view considerably more than 80 characters on even my 13" laptop at home.
What I'd rather see is a guideline like, "Try to keep your lines to 120 characters at most. If you cannot easily refactor code to use shorter lines, here is the recommended best practice of spanning multiple lines...."
- using instance variables only when you *really* need it
- 'do...end' and curly braces conventions (?)
- CamelCaseOnlyForClassNames
Some of these are standard Ruby conventions, e.g., using curly braces only for one-liners, vs. do..end for multi-line blocks, or CamelCaseOnlyForClassNames. I seem to recall having read a really great overview of many common Ruby conventions in the past, but, of course, I cannot find it now.
Personally, I'd rather our list was more a set of "Best Practices" or "Preferred Conventions" to help us be more consistent, versus a set of mandatory rules. Some larger projects (which shall remain nameless) seem to irritate a lot of people by having rigid requirements that presumably started off as well-intentioned guidelines to help keep things consistent/structured, but turned into a set of hurdles that don't always have any benefit.
Do you want to take a stab at throwing some of these up the wiki, and others can add more (or object to some of them)? I have a few more I can think of adding.
Jim Meyering actually did a lot of work on coding standards at one point, including the infamous no-trailing-whitespace rule.
We had also had a hard 80-character line limit at one point, which I wholeheartedly support... but seeing as how I don't submit very many patches I don't have a leg to stand on.
However in all of this discussion I would urge the community to consult the grizzled veterans among you (Jim is a good example) -- they've hashed through these issues many many times before and can tell you in precise detail *why* a particular standard is a good idea or not.
--Hugh
On 04/26/2012 12:15 PM, Hugh O. Brock wrote:
On Thu, Apr 26, 2012 at 12:04:06PM -0400, Matt Wagner wrote:
On Thu, Apr 26, 2012 at 05:25:04PM +0200, Maros Zatko wrote:
Hi everybody,
I'd love to ask you if we have some coding style guidelines. If we don't I'd like to propose creating such thing and start to enforce it in a review process.
To my knowledge, all we really have is a notion of what others have done in the past. But I think it would be a good idea to start to write those things up on a wiki page.
some of the guidelines ideas are:
- 2 spaces over tabs
- fuzzy (i.e. non-strict limit) for 80 chars per line (and yes - 120
chars are way too much)
I'm not sure I completely agree with this one. There is certainly some point at which lines are too long, but I'm not sure 80 characters is it. It feels like a carryover from VT100 days, and I can view considerably more than 80 characters on even my 13" laptop at home.
What I'd rather see is a guideline like, "Try to keep your lines to 120 characters at most. If you cannot easily refactor code to use shorter lines, here is the recommended best practice of spanning multiple lines...."
- using instance variables only when you *really* need it
- 'do...end' and curly braces conventions (?)
- CamelCaseOnlyForClassNames
Some of these are standard Ruby conventions, e.g., using curly braces only for one-liners, vs. do..end for multi-line blocks, or CamelCaseOnlyForClassNames. I seem to recall having read a really great overview of many common Ruby conventions in the past, but, of course, I cannot find it now.
Personally, I'd rather our list was more a set of "Best Practices" or "Preferred Conventions" to help us be more consistent, versus a set of mandatory rules. Some larger projects (which shall remain nameless) seem to irritate a lot of people by having rigid requirements that presumably started off as well-intentioned guidelines to help keep things consistent/structured, but turned into a set of hurdles that don't always have any benefit.
Do you want to take a stab at throwing some of these up the wiki, and others can add more (or object to some of them)? I have a few more I can think of adding.
Jim Meyering actually did a lot of work on coding standards at one point, including the infamous no-trailing-whitespace rule.
We had also had a hard 80-character line limit at one point, which I wholeheartedly support... but seeing as how I don't submit very many patches I don't have a leg to stand on.
I already commented on the char limit in another message, but since you mention the hard limit here, I'll comment further. Those who oppose the limit point out that "screens are wider these days," but they forget entirely that many of us (myself and probably also jim and clalance -- who both advocated for the hard limit of 80 chars) will use two side-by-side buffers to see more code on the screen at once. In my case, I get 87 chars per buffer before wraparound with two side-by-side buffers in emacs on my 12" X-series screen, using default font sizing.
However, I'd rather advocate for an 80 char "soft" limit. i.e. Limit to 80 chars, unless doing so would be really awkward. Ruby doesn't always make line breaks easy to do, and sometimes the hoops you have to jump through to avoid wraparound results in code that is _less_ readable than if it simply wrapped around in an 80-char-wide buffer, as long as the number of wrapped-around lines is relatively small.
However in all of this discussion I would urge the community to consult the grizzled veterans among you (Jim is a good example) -- they've hashed through these issues many many times before and can tell you in precise detail *why* a particular standard is a good idea or not.
--Hugh
On 04/26/2012 12:15 PM, Hugh O. Brock wrote:
On Thu, Apr 26, 2012 at 12:04:06PM -0400, Matt Wagner wrote:
On Thu, Apr 26, 2012 at 05:25:04PM +0200, Maros Zatko wrote:
Hi everybody,
I'd love to ask you if we have some coding style guidelines. If we don't I'd like to propose creating such thing and start to enforce it in a review process.
To my knowledge, all we really have is a notion of what others have done in the past. But I think it would be a good idea to start to write those things up on a wiki page.
some of the guidelines ideas are:
- 2 spaces over tabs
- fuzzy (i.e. non-strict limit) for 80 chars per line (and yes - 120
chars are way too much)
I'm not sure I completely agree with this one. There is certainly some point at which lines are too long, but I'm not sure 80 characters is it. It feels like a carryover from VT100 days, and I can view considerably more than 80 characters on even my 13" laptop at home.
What I'd rather see is a guideline like, "Try to keep your lines to 120 characters at most. If you cannot easily refactor code to use shorter lines, here is the recommended best practice of spanning multiple lines...."
- using instance variables only when you *really* need it
- 'do...end' and curly braces conventions (?)
- CamelCaseOnlyForClassNames
Some of these are standard Ruby conventions, e.g., using curly braces only for one-liners, vs. do..end for multi-line blocks, or CamelCaseOnlyForClassNames. I seem to recall having read a really great overview of many common Ruby conventions in the past, but, of course, I cannot find it now.
Personally, I'd rather our list was more a set of "Best Practices" or "Preferred Conventions" to help us be more consistent, versus a set of mandatory rules. Some larger projects (which shall remain nameless) seem to irritate a lot of people by having rigid requirements that presumably started off as well-intentioned guidelines to help keep things consistent/structured, but turned into a set of hurdles that don't always have any benefit.
Do you want to take a stab at throwing some of these up the wiki, and others can add more (or object to some of them)? I have a few more I can think of adding.
Jim Meyering actually did a lot of work on coding standards at one point, including the infamous no-trailing-whitespace rule.
We had also had a hard 80-character line limit at one point, which I wholeheartedly support... but seeing as how I don't submit very many patches I don't have a leg to stand on.
I already commented on the char limit in another message, but since you mention the hard limit here, I'll comment further. Those who oppose the limit point out that "screens are wider these days," but they forget entirely that many of us (myself and probably also jim and clalance -- who both advocated for the hard limit of 80 chars) will use two side-by-side buffers to see more code on the screen at once. In my case, I get 87 chars per buffer before wraparound with two side-by-side buffers in emacs on my 12" X-series screen, using default font sizing.
However, I'd rather advocate for an 80 char "soft" limit. i.e. Limit to 80 chars, unless doing so would be really awkward. Ruby doesn't always make line breaks easy to do, and sometimes the hoops you have to jump through to avoid wraparound results in code that is _less_ readable than if it simply wrapped around in an 80-char-wide buffer, as long as the number of wrapped-around lines is relatively small.
However in all of this discussion I would urge the community to consult the grizzled veterans among you (Jim is a good example) -- they've hashed through these issues many many times before and can tell you in precise detail *why* a particular standard is a good idea or not.
--Hugh
On 26/04/12 12:36 -0400, Scott Seago wrote:
On 04/26/2012 12:15 PM, Hugh O. Brock wrote:
On Thu, Apr 26, 2012 at 12:04:06PM -0400, Matt Wagner wrote:
On Thu, Apr 26, 2012 at 05:25:04PM +0200, Maros Zatko wrote:
Hi everybody,
I'd love to ask you if we have some coding style guidelines. If we don't I'd like to propose creating such thing and start to enforce it in a review process.
To my knowledge, all we really have is a notion of what others have done in the past. But I think it would be a good idea to start to write those things up on a wiki page.
some of the guidelines ideas are:
- 2 spaces over tabs
- fuzzy (i.e. non-strict limit) for 80 chars per line (and yes - 120
chars are way too much)
I'm not sure I completely agree with this one. There is certainly some point at which lines are too long, but I'm not sure 80 characters is it. It feels like a carryover from VT100 days, and I can view considerably more than 80 characters on even my 13" laptop at home.
What I'd rather see is a guideline like, "Try to keep your lines to 120 characters at most. If you cannot easily refactor code to use shorter lines, here is the recommended best practice of spanning multiple lines...."
- using instance variables only when you *really* need it
- 'do...end' and curly braces conventions (?)
- CamelCaseOnlyForClassNames
Some of these are standard Ruby conventions, e.g., using curly braces only for one-liners, vs. do..end for multi-line blocks, or CamelCaseOnlyForClassNames. I seem to recall having read a really great overview of many common Ruby conventions in the past, but, of course, I cannot find it now.
Personally, I'd rather our list was more a set of "Best Practices" or "Preferred Conventions" to help us be more consistent, versus a set of mandatory rules. Some larger projects (which shall remain nameless) seem to irritate a lot of people by having rigid requirements that presumably started off as well-intentioned guidelines to help keep things consistent/structured, but turned into a set of hurdles that don't always have any benefit.
Do you want to take a stab at throwing some of these up the wiki, and others can add more (or object to some of them)? I have a few more I can think of adding.
Jim Meyering actually did a lot of work on coding standards at one point, including the infamous no-trailing-whitespace rule.
We had also had a hard 80-character line limit at one point, which I wholeheartedly support... but seeing as how I don't submit very many patches I don't have a leg to stand on.
I already commented on the char limit in another message, but since you mention the hard limit here, I'll comment further. Those who oppose the limit point out that "screens are wider these days," but they forget entirely that many of us (myself and probably also jim and clalance -- who both advocated for the hard limit of 80 chars) will use two side-by-side buffers to see more code on the screen at once. In my case, I get 87 chars per buffer before wraparound with two side-by-side buffers in emacs on my 12" X-series screen, using default font sizing.
However, I'd rather advocate for an 80 char "soft" limit. i.e. Limit to 80 chars, unless doing so would be really awkward. Ruby doesn't always make line breaks easy to do, and sometimes the hoops you have to jump through to avoid wraparound results in code that is _less_ readable than if it simply wrapped around in an 80-char-wide buffer, as long as the number of wrapped-around lines is relatively small.
+1 to this. I totally agree with the sentiment that 'screens are wider these days' is not a relevant metric. Anyone who uses emacs, vim, screen, tmux- or heck, even an ide- may frequently have 2 files open side by side, thus effectively cutting screen with in half (yes, I added IDE to the list so martyn would feel included). Granted that almost any modern editor can wrap lies as you mention in the emacs example, but I don't feel that is a strong enough argument to advocate long lines lengths other than in rare situations where they cannot be avoided (and imo, these situations should be _exceedingly_ rare).
Aside from this one point, I think in general, we should follow ruby community standards, as this is a ruby project. I have not read Michal's link yet, but given how respected github is, I suspect their guidelines a probably pretty close to those of the overall ruby community.
-j
However in all of this discussion I would urge the community to consult the grizzled veterans among you (Jim is a good example) -- they've hashed through these issues many many times before and can tell you in precise detail *why* a particular standard is a good idea or not.
--Hugh
On 27/04/2012, at 2:50 AM, Jason Guiditta wrote: <snip>
Aside from this one point, I think in general, we should follow ruby community standards, as this is a ruby project.
+1
Just because it keeps things that little bit easier, for anyone who's an existing experienced Ruby coder.
+ Justin
-- Aeolus Community Manager http://www.aeolusproject.org
On 04/26/2012 12:04 PM, Matt Wagner wrote:
On Thu, Apr 26, 2012 at 05:25:04PM +0200, Maros Zatko wrote:
Hi everybody,
I'd love to ask you if we have some coding style guidelines. If we don't I'd like to propose creating such thing and start to enforce it in a review process.
To my knowledge, all we really have is a notion of what others have done in the past. But I think it would be a good idea to start to write those things up on a wiki page.
some of the guidelines ideas are:
- 2 spaces over tabs
- fuzzy (i.e. non-strict limit) for 80 chars per line (and yes - 120
chars are way too much)
I'm not sure I completely agree with this one. There is certainly some point at which lines are too long, but I'm not sure 80 characters is it. It feels like a carryover from VT100 days, and I can view considerably more than 80 characters on even my 13" laptop at home.
You're assuming everyone uses full-screen-width buffers. Unless I'm editing a file which has much longer-than-average lines, I always have two buffers side-by-side in emacs. Usually this is on my 12" X-series laptop screen -- on here with default editor font size, each buffer can hold 87 chars before scrolling. That said, I do _not_ favor a strict 80 col limit (unlike some on the team have expressed a preference for in the past). Ruby makes line breaking more difficult than some other languages, and I'd rather see an occasional scroll-around than a really awkward line break. That said, as stated above, if most of your lines are 120 chars long you're doing something wrong and it will be hard for me to read on my 87-character-wide buffers.
What I'd rather see is a guideline like, "Try to keep your lines to 120 characters at most. If you cannot easily refactor code to use shorter lines, here is the recommended best practice of spanning multiple lines...."
I agree with having a flexible guideline, but again I don't want to see most lines >100 chars long (since they'll all scroll for me). In most cases, all you have to do is split args across multiple lines, or array elements, or whatever -- basically if you hit a point where you have a comma and you're at 75 chars or more, continue on the next line. Many of our too-long lines can be fixed fairly easily this way. For me, it's more obvious when I need to break a line -- when it wraps around in my own editor.
- using instance variables only when you *really* need it
- 'do...end' and curly braces conventions (?)
- CamelCaseOnlyForClassNames
Some of these are standard Ruby conventions, e.g., using curly braces only for one-liners, vs. do..end for multi-line blocks, or CamelCaseOnlyForClassNames. I seem to recall having read a really great overview of many common Ruby conventions in the past, but, of course, I cannot find it now.
Personally, I'd rather our list was more a set of "Best Practices" or "Preferred Conventions" to help us be more consistent, versus a set of mandatory rules. Some larger projects (which shall remain nameless) seem to irritate a lot of people by having rigid requirements that presumably started off as well-intentioned guidelines to help keep things consistent/structured, but turned into a set of hurdles that don't always have any benefit.
Do you want to take a stab at throwing some of these up the wiki, and others can add more (or object to some of them)? I have a few more I can think of adding.
-- Matt
On 04/26/2012 06:04 PM, Matt Wagner wrote:
On Thu, Apr 26, 2012 at 05:25:04PM +0200, Maros Zatko wrote:
Hi everybody,
I'd love to ask you if we have some coding style guidelines. If we don't I'd like to propose creating such thing and start to enforce it in a review process.
An excellent idea. Having consistent code makes it easier to maintain and review.
To my knowledge, all we really have is a notion of what others have done in the past. But I think it would be a good idea to start to write those things up on a wiki page.
some of the guidelines ideas are:
- 2 spaces over tabs
- fuzzy (i.e. non-strict limit) for 80 chars per line (and yes - 120
chars are way too much)
I'm not sure I completely agree with this one. There is certainly some point at which lines are too long, but I'm not sure 80 characters is it. It feels like a carryover from VT100 days, and I can view considerably more than 80 characters on even my 13" laptop at home.
What I'd rather see is a guideline like, "Try to keep your lines to 120 characters at most. If you cannot easily refactor code to use shorter lines, here is the recommended best practice of spanning multiple lines...."
Lets not try to create our own guidelines and try to find some existing conventions. Actually most IDEs allow your to format code after you've written it. If we decide to do this we could create templates for eclipse, rubymine and vim. Then its as easy as clicking on "format". Alternatively there may already be some git hooks we can install locally that check code format on commit or add.
- using instance variables only when you *really* need it
- 'do...end' and curly braces conventions (?)
- CamelCaseOnlyForClassNames
Some of these are standard Ruby conventions, e.g., using curly braces only for one-liners, vs. do..end for multi-line blocks, or CamelCaseOnlyForClassNames. I seem to recall having read a really great overview of many common Ruby conventions in the past, but, of course, I cannot find it now.
Personally, I'd rather our list was more a set of "Best Practices" or "Preferred Conventions" to help us be more consistent, versus a set of mandatory rules. Some larger projects (which shall remain nameless) seem to irritate a lot of people by having rigid requirements that presumably started off as well-intentioned guidelines to help keep things consistent/structured, but turned into a set of hurdles that don't always have any benefit.
Yeah I think we probably need to have a best practice sheet and a strict format.
Do you want to take a stab at throwing some of these up the wiki, and others can add more (or object to some of them)? I have a few more I can think of adding.
Here are a couple of things:
* Do not squeeze everything on one line.
One thing that really irritates me is the need for people to try and squeeze every thing on one line. It is true that less lines of code means less maintenence of code. But it gets to a point when it is rediculous, I've seen people write whole methods and try to squeeze them on 1 line. It just makes the whole thing impossible to read.
* Don't be afraid to use local variables.
Again on the same lines as the previous comment. We should be concentrating on easy to read code, if this means assigning a few local variables so we don't have massive lookups all over the place then we should do
* Proper Exception Handling.
Since exceptions seems to be handled particularly badly in conductor and others places. We should write a guide on how to handle these properly. One this I have noticed is that people never raise exceptions, and often exceptions are caught without logging them - among other thin
* Method size guidelines.
If you find you have to write comments all over the place in the code then the likelihood is that your code is too long and complex. The method signatures should be enough to describe what is going on. Obviously it depends on the situation but I'd say no more than around 10 lines per method.
If we get into the habit of checking all these things in the review process then I feel we'll really be on our way to cleaning up the codebase.
Regards
Martyn
-- Matt
On Thu, Apr 26, 2012 at 05:25:04PM +0200, Maros Zatko wrote:
Hi everybody,
I'd love to ask you if we have some coding style guidelines. If we don't I'd like to propose creating such thing and start to enforce it in a review process.
After we discussed some of this some more on IRC, I just threw this together: https://www.aeolusproject.org/redmine/projects/aeolus/wiki/Coding_Guidelines
I would propose that, in general, we should just rely on the existing style guide (linked at the top), except where we want to override it, or repeat something for emphasis. (In other words, think of our "Coding Guidelines" page as descending from the linked Ruby Style Guide.)
There's still probably lots more to do. Feel free to expand! (It is, after all, a wiki.)
-- Matt
aeolus-devel@lists.fedorahosted.org