Coding style guidelines

Martyn Taylor mtaylor at redhat.com
Fri Apr 27 09:43:54 UTC 2012


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




More information about the aeolus-devel mailing list