[GenABEL-dev] GenABEL project style guide

[L.C. Karssen]

Dear all,

Maarten started an etherpad instance at http://openetherpad.org/oxx0htdP47
I've updated the text he and I came up with and reformatted it in Emacs
org-mode, which allows easy export to PDF and HTML (so that we can
easily integrated it in the development website on r-forge as per
Yurii's suggestion).

If I don't see much change in the EtherPad document in the coming days
I'll put the org file and its HTML export in SVN.


Lennart.

On 20/03/13 11:54, Yurii Aulchenko wrote:
> Hi Lennart,
> 
> Indeed, why do not we set up piratpad; or we can use our SVN, the same
> section we have tutorials in - then it will go directly
> to http://genabel.r-forge.r-project.org/
> 
> I think it is important to have guidelines  and I personally will try to
> follow them as much as I could.
> 
> At the same time, I would like to emphasize that we had the idea that
> rules and guidelines should be suggestive, so that even if I do not
> comply 100% I can still make it into the project, and then can improve
> on the way. See the quote below.
> 
> best, Yurii
> 
> Quote from
> 
> http://www.genabel.org/developers:
> 
> Rules of the game
> The documents provided here are meant to help. We are scared to think of
> a situation when 'guidelines' and 'rules' prevent people from
> contributing to the project, and a willing contributor is discouraged by
> just looking at the pile of 'rules'.
> 
> On Mon, Mar 18, 2013 at 9:32 AM, L.C. Karssen <lennart at karssen.org
> <mailto:lennart at karssen.org>> wrote:
> 
>     Dear all,
> 
>     I'd like to follow up on something Yurii wrote in the discussion on the
>     GenABEL tutorial:
> 
>     On 03/14/2013 09:38 AM, Yurii Aulchenko wrote:
>     > I agree that full argument names should be preferred. I was just being
>     > lazy; I am trying to improve. If other people come up with things
>     > which are "not in good style" we should probably think of a "good
>     > style rules" document and then ask people to please to follow them.
>     >
> 
>     I completely agree with Yurii. In fact, I think we should not only set
>     guidelines for the style of the code in the tutorial, but more generally
>     for all R and C/C++ code in the GenABEL project.
> 
>     What about setting up a shared editing environment (e.g. on
>     piratepad.net <http://piratepad.net>) to work on an initial draft of
>     these quidelines? Once
>     they are more or less fixed we can move the document to SVN as part of
>     the developer documentation.
> 
>     From my experience over the last few years I think the following points
>     are the most commonly occurring ones (for any language) that need
>     harmonisation:
>     - comma's should be followed by a space
>     - operators (= + - * etc.) should be surrounded by a space (and in R the
>     <- operator too)
>     - a file should always have a newline at the end
>     - don't use tabs (as everyone seems to have a different setting for the
>     tab stop): use spaces. How many spaces is up for debate. Of course
>     Makefiles are exempt from this rule as tabs are mandatory
>     - style of brackets: is the opening bracket on the same line as the name
>     of the loop/function or on a new line on its own? (e.g. K&R, Allman or
>     bsd style)
>     - always use {} in if clauses/for loops (even if there is only one
>     statement in the clause/loop
>     - lines should not be longer than 80 characters (you may call me old
>     fashioned ;-))
> 
>     I think most of these can be set as options in modern development
>     environment. I'm not an Eclipse user, like many of you, but in Emacs
>     these can easily be set in your .emacs file. We should also provide info
>     on how to implement these settings in various DEs in our guidelines
>     document so that new developers can easily use them.
> 
> 
>     Lennart.
>     --
>     -----------------------------------------------------------------
>     L.C. Karssen
>     Utrecht
>     The Netherlands
> 
>     lennart at karssen.org <mailto:lennart at karssen.org>
>     http://blog.karssen.org
> 
>     Stuur mij aub geen Word of Powerpoint bestanden!
>     Zie http://www.gnu.org/philosophy/no-word-attachments.nl.html
>     ------------------------------------------------------------------
> 
> 
>     _______________________________________________
>     genabel-devel mailing list
>     genabel-devel at lists.r-forge.r-project.org
>     <mailto:genabel-devel at lists.r-forge.r-project.org>
>     https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/genabel-devel
> 
> 
> 
> 
> -- 
> -----------------------------------------------------
> Yurii S. Aulchenko
> 
> [ LinkedIn <http://nl.linkedin.com/in/yuriiaulchenko> ] [ Twitter
> <http://twitter.com/YuriiAulchenko> ] [ Blog
> <http://yurii-aulchenko.blogspot.nl/> ]

-- 
-----------------------------------------------------------------
L.C. Karssen
Utrecht
The Netherlands

lennart at karssen.org
http://blog.karssen.org

Stuur mij aub geen Word of Powerpoint bestanden!
Zie http://www.gnu.org/philosophy/no-word-attachments.nl.html
------------------------------------------------------------------

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 230 bytes
Desc: OpenPGP digital signature
URL: <http://lists.r-forge.r-project.org/pipermail/genabel-devel/attachments/20130321/1afa178a/attachment.sig>