[Genabel-commits] r1215 - www
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Tue May 14 00:06:57 CEST 2013
Author: lckarssen
Date: 2013-05-14 00:06:54 +0200 (Tue, 14 May 2013)
New Revision: 1215
Added:
www/codingstyle.html
www/codingstyle.org
Log:
Added the first draft of the GenABEL coding standards document to the www directory.
The .org file is the source document, please edit that and export to HTML. Normally files derived from other files shouldn't be in SVN, but in this case I make an exemption because the HTML file can be directly viewed from the GenABEL R-forge website.
To export from the command line use:
emacs -batch --eval '(and (find-file "codingstyle.org") (org-export-as-html nil))'
Added: www/codingstyle.html
===================================================================
--- www/codingstyle.html (rev 0)
+++ www/codingstyle.html 2013-05-13 22:06:54 UTC (rev 1215)
@@ -0,0 +1,378 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+<head>
+<title>GenABEL project coding style guidelines</title>
+<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"/>
+<meta name="title" content="GenABEL project coding style guidelines"/>
+<meta name="generator" content="Org-mode"/>
+<meta name="generated" content="2013-05-14T00:05+0200"/>
+<meta name="author" content="The GenABEL development team"/>
+<meta name="description" content=""/>
+<meta name="keywords" content=""/>
+<style type="text/css">
+ <!--/*--><![CDATA[/*><!--*/
+ html { font-family: Times, serif; font-size: 12pt; }
+ .title { text-align: center; }
+ .todo { color: red; }
+ .done { color: green; }
+ .tag { background-color: #add8e6; font-weight:normal }
+ .target { }
+ .timestamp { color: #bebebe; }
+ .timestamp-kwd { color: #5f9ea0; }
+ .right {margin-left:auto; margin-right:0px; text-align:right;}
+ .left {margin-left:0px; margin-right:auto; text-align:left;}
+ .center {margin-left:auto; margin-right:auto; text-align:center;}
+ p.verse { margin-left: 3% }
+ pre {
+ border: 1pt solid #AEBDCC;
+ background-color: #F3F5F7;
+ padding: 5pt;
+ font-family: courier, monospace;
+ font-size: 90%;
+ overflow:auto;
+ }
+ table { border-collapse: collapse; }
+ td, th { vertical-align: top; }
+ th.right { text-align:center; }
+ th.left { text-align:center; }
+ th.center { text-align:center; }
+ td.right { text-align:right; }
+ td.left { text-align:left; }
+ td.center { text-align:center; }
+ dt { font-weight: bold; }
+ div.figure { padding: 0.5em; }
+ div.figure p { text-align: center; }
+ div.inlinetask {
+ padding:10px;
+ border:2px solid gray;
+ margin:10px;
+ background: #ffffcc;
+ }
+ textarea { overflow-x: auto; }
+ .linenr { font-size:smaller }
+ .code-highlighted {background-color:#ffff00;}
+ .org-info-js_info-navigation { border-style:none; }
+ #org-info-js_console-label { font-size:10px; font-weight:bold;
+ white-space:nowrap; }
+ .org-info-js_search-highlight {background-color:#ffff00; color:#000000;
+ font-weight:bold; }
+ /*]]>*/-->
+</style>
+<script type="text/javascript">
+/*
+ at licstart The following is the entire license notice for the
+JavaScript code in this tag.
+
+Copyright (C) 2012 Free Software Foundation, Inc.
+
+The JavaScript code in this tag is free software: you can
+redistribute it and/or modify it under the terms of the GNU
+General Public License (GNU GPL) as published by the Free Software
+Foundation, either version 3 of the License, or (at your option)
+any later version. The code is distributed WITHOUT ANY WARRANTY;
+without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
+
+As additional permission under GNU GPL version 3 section 7, you
+may distribute non-source (e.g., minimized or compacted) forms of
+that code without the copy of the GNU GPL normally required by
+section 4, provided you include this license notice and a URL
+through which recipients can access the Corresponding Source.
+
+
+ at licend The above is the entire license notice
+for the JavaScript code in this tag.
+*/
+<!--/*--><![CDATA[/*><!--*/
+ function CodeHighlightOn(elem, id)
+ {
+ var target = document.getElementById(id);
+ if(null != target) {
+ elem.cacheClassElem = elem.className;
+ elem.cacheClassTarget = target.className;
+ target.className = "code-highlighted";
+ elem.className = "code-highlighted";
+ }
+ }
+ function CodeHighlightOff(elem, id)
+ {
+ var target = document.getElementById(id);
+ if(elem.cacheClassElem)
+ elem.className = elem.cacheClassElem;
+ if(elem.cacheClassTarget)
+ target.className = elem.cacheClassTarget;
+ }
+/*]]>*///-->
+</script>
+
+</head>
+<body>
+
+<div id="preamble">
+
+</div>
+
+<div id="content">
+<h1 class="title">GenABEL project coding style guidelines</h1>
+
+<p>This document describes the coding style guidelines of the GenABEL
+project. At present it is considered <b>work in progress</b>. As the name
+says these are guidelines, not rules. We don't want these guidelines
+to restrict people from contributing code to the project. On the other
+hand, respecting these guidelines will lead to uniform and more easily
+maintainable code and consequently we encourage everyone to follow
+them.
+</p>
+
+<div id="table-of-contents">
+<h2>Table of Contents</h2>
+<div id="text-table-of-contents">
+<ul>
+<li><a href="#sec-1">1 General</a>
+<ul>
+<li><a href="#sec-1-1">1.1 White space</a></li>
+<li><a href="#sec-1-2">1.2 Other</a></li>
+</ul>
+</li>
+<li><a href="#sec-2">2 R</a>
+<ul>
+<li><a href="#sec-2-1">2.1 Code</a></li>
+<li><a href="#sec-2-2">2.2 Documentation</a></li>
+</ul>
+</li>
+<li><a href="#sec-3">3 C/C++</a></li>
+<li><a href="#sec-4">4 LaTeX</a></li>
+<li><a href="#sec-5">5 Configuring editors and IDEs to support the guidelines</a>
+<ul>
+<li><a href="#sec-5-1">5.1 Eclipse</a></li>
+<li><a href="#sec-5-2">5.2 Emacs</a></li>
+</ul>
+</li>
+</ul>
+</div>
+</div>
+
+<div id="outline-container-1" class="outline-2">
+<h2 id="sec-1"><span class="section-number-2">1</span> General</h2>
+<div class="outline-text-2" id="text-1">
+
+
+</div>
+
+<div id="outline-container-1-1" class="outline-3">
+<h3 id="sec-1-1"><span class="section-number-3">1.1</span> White space</h3>
+<div class="outline-text-3" id="text-1-1">
+
+<ul>
+<li>comma's should be followed by a space
+</li>
+<li>operators (<code>= + - *</code> etc.) should be surrounded by a space (and in R
+ the <code><-</code> operator too)
+</li>
+<li>a file should always have a newline at the end (Why?)
+</li>
+<li>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
+</li>
+<li>no (unnessary) empty lines
+</li>
+</ul>
+
+</div>
+
+</div>
+
+<div id="outline-container-1-2" class="outline-3">
+<h3 id="sec-1-2"><span class="section-number-3">1.2</span> Other</h3>
+<div class="outline-text-3" id="text-1-2">
+
+<ul>
+<li>lines should not be longer than 80 characters
+</li>
+<li>do not use one charcter variables, except when it is a counter in a loop
+</li>
+<li>issues to be be fixed should be represented as:
+
+
+
+<pre class="example">//FIXME(name_of_person): explanation what is wrong.
+</pre>
+
+<p>
+ This makes looking and finxing for this types of problems easier
+</p></li>
+<li>things to do must be annotated with:
+
+
+
+<pre class="example">//TODO(name_of_person): explain what to do
+</pre>
+
+<p>
+ Don't be shy and put your name in there if this is something that
+ you expect will take a while.
+</p></li>
+<li>code that is old/broken should be removed (we have our version
+ control system so we can always go back to see how things were in
+ the past)
+</li>
+<li>functions should not contain more than ~30 lines. If you need
+ more: you probably need a new function anyway to separate
+ logical parts of the code.
+</li>
+<li>seperate code that outputs to file or console from rest of the code
+</li>
+</ul>
+
+</div>
+</div>
+
+</div>
+
+<div id="outline-container-2" class="outline-2">
+<h2 id="sec-2"><span class="section-number-2">2</span> R</h2>
+<div class="outline-text-2" id="text-2">
+
+
+</div>
+
+<div id="outline-container-2-1" class="outline-3">
+<h3 id="sec-2-1"><span class="section-number-3">2.1</span> Code</h3>
+<div class="outline-text-3" id="text-2-1">
+
+<ul>
+<li>Use the <code><-</code> operator for assignments, not <code>=</code>
+</li>
+<li>use codetools in R to check your functions
+</li>
+</ul>
+
+</div>
+
+</div>
+
+<div id="outline-container-2-2" class="outline-3">
+<h3 id="sec-2-2"><span class="section-number-3">2.2</span> Documentation</h3>
+<div class="outline-text-3" id="text-2-2">
+
+<p> We prefer that all documentation should be in roxygen2 format.
+</p></div>
+</div>
+
+</div>
+
+<div id="outline-container-3" class="outline-2">
+<h2 id="sec-3"><span class="section-number-2">3</span> C/C++</h2>
+<div class="outline-text-2" id="text-3">
+
+<ul>
+<li>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) <b>TODO: decide which one</b>
+</li>
+<li>both brackets of else statements should be on the same line
+ <b>Depends on previous item</b>
+</li>
+<li>always use {} in if clauses/for loops (even if there is only one
+ statement in the clause/loop
+</li>
+<li>make sure your code compiles without warnings/errors using
+
+
+
+<pre class="example">gcc -wall
+</pre>
+
+</li>
+</ul>
+
+</div>
+
+</div>
+
+<div id="outline-container-4" class="outline-2">
+<h2 id="sec-4"><span class="section-number-2">4</span> LaTeX</h2>
+<div class="outline-text-2" id="text-4">
+
+</div>
+
+</div>
+
+<div id="outline-container-5" class="outline-2">
+<h2 id="sec-5"><span class="section-number-2">5</span> Configuring editors and IDEs to support the guidelines</h2>
+<div class="outline-text-2" id="text-5">
+
+
+</div>
+
+<div id="outline-container-5-1" class="outline-3">
+<h3 id="sec-5-1"><span class="section-number-3">5.1</span> Eclipse</h3>
+<div class="outline-text-3" id="text-5-1">
+
+</div>
+
+</div>
+
+<div id="outline-container-5-2" class="outline-3">
+<h3 id="sec-5-2"><span class="section-number-3">5.2</span> Emacs</h3>
+<div class="outline-text-3" id="text-5-2">
+
+
+
+
+<pre class="src src-lisp"><span style="font-weight: bold; font-style: italic;">;;; </span><span style="font-weight: bold; font-style: italic;">Trailing white space stuff</span>
+<span style="font-weight: bold; font-style: italic;">;; </span><span style="font-weight: bold; font-style: italic;">Show trailing white space in orange</span>
+(setq-default show-trailing-whitespace t)
+(set-face-background 'trailing-whitespace <span style="font-style: italic;">"orange1"</span>)
+<span style="font-weight: bold; font-style: italic;">;; </span><span style="font-weight: bold; font-style: italic;">nuke whitespaces when writing to a file</span>
+(add-hook 'before-save-hook 'whitespace-cleanup)
+<span style="font-weight: bold; font-style: italic;">;; </span><span style="font-weight: bold; font-style: italic;">Don't insert tabs when indenting regions (setq-default is used here</span>
+<span style="font-weight: bold; font-style: italic;">;; </span><span style="font-weight: bold; font-style: italic;">to only overwrite this in buffers that do not have their own local</span>
+<span style="font-weight: bold; font-style: italic;">;; </span><span style="font-weight: bold; font-style: italic;">values for this variable)</span>
+(setq-default indent-tabs-mode nil)
+
+<span style="font-weight: bold; font-style: italic;">;;; </span><span style="font-weight: bold; font-style: italic;">ESS mode (R, S, etc.)</span>
+(add-hook 'ess-mode-hook
+ (<span style="font-weight: bold;">lambda</span> ()
+ (auto-fill-mode t) <span style="font-weight: bold; font-style: italic;">; </span><span style="font-weight: bold; font-style: italic;">Turn on auto-fill-mode</span>
+ <span style="font-weight: bold; font-style: italic;">; </span><span style="font-weight: bold; font-style: italic;">Set pdflatex as the default command for Sweave (default: texi2pdf)</span>
+ (setq ess-swv-pdflatex-commands (quote (<span style="font-style: italic;">"pdflatex"</span> <span style="font-style: italic;">"texi2pdf"</span> <span style="font-style: italic;">"make"</span>)))
+ ))
+
+
+<span style="font-weight: bold; font-style: italic;">;;; </span><span style="font-weight: bold; font-style: italic;">C-mode:</span>
+<span style="font-weight: bold; font-style: italic;">;; </span><span style="font-weight: bold; font-style: italic;">change C indentation style ("{" directly under "for" etc.)</span>
+(setq c-default-style <span style="font-style: italic;">"bsd"</span>
+ c-basic-offset 4) <span style="font-weight: bold; font-style: italic;">; </span><span style="font-weight: bold; font-style: italic;">Indentation of 4 spaces</span>
+<span style="font-weight: bold; font-style: italic;">;; </span><span style="font-weight: bold; font-style: italic;">Turn on auto fill mode (max 80 columns)</span>
+(add-hook 'c-mode-common-hook 'auto-fill-mode)
+
+<span style="font-weight: bold; font-style: italic;">;;; </span><span style="font-weight: bold; font-style: italic;">LaTeX using AucTeX</span>
+(load <span style="font-style: italic;">"auctex.el"</span> nil t t)
+(add-hook 'LaTeX-mode-hook
+(<span style="font-weight: bold;">lambda</span>()
+ 'turn-on-auto-fill <span style="font-weight: bold; font-style: italic;">; </span><span style="font-weight: bold; font-style: italic;">Set max of 80 columns</span>
+ ))
+
+ <span style="font-weight: bold; font-style: italic;">;; </span><span style="font-weight: bold; font-style: italic;">Emacs' regular latex mode (when AucTeX isn't present)</span>
+ (add-hook 'latex-mode-hook 'turn-on-reftex)
+ (add-hook 'latex-mode-hook 'turn-on-auto-fill)
+</pre>
+
+</div>
+</div>
+</div>
+</div>
+
+<div id="postamble">
+<p class="date">Date: 2013-05-14T00:05+0200</p>
+<p class="author">Author: The GenABEL development team</p>
+<p class="creator"><a href="http://orgmode.org">Org</a> version 7.9.2 with <a href="http://www.gnu.org/software/emacs/">Emacs</a> version 24</p>
+<a href="http://validator.w3.org/check?uri=referer">Validate XHTML 1.0</a>
+
+</div>
+</body>
+</html>
Added: www/codingstyle.org
===================================================================
--- www/codingstyle.org (rev 0)
+++ www/codingstyle.org 2013-05-13 22:06:54 UTC (rev 1215)
@@ -0,0 +1,114 @@
+#+TITLE: GenABEL project coding style guidelines
+#+AUTHOR: The GenABEL development team
+#+EMAIL:
+#+DESCRIPTION:
+#+KEYWORDS:
+#+LANGUAGE: en
+#+OPTIONS: H:3 num:t toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
+#+OPTIONS: TeX:t LaTeX:t skip:nil d:nil todo:t pri:t tags:nil
+#+INFOJS_OPT: view:nil toc:nil ltoc:t mouse:underline buttons:0 path:http://orgmode.org/org-info.js
+#+EXPORT_SELECT_TAGS: export
+#+EXPORT_EXCLUDE_TAGS: noexport
+#+LINK_UP:
+#+LINK_HOME:
+#+XSLT:
+This document describes the coding style guidelines of the GenABEL
+project. At present it is considered *work in progress*. As the name
+says these are guidelines, not rules. We don't want these guidelines
+to restrict people from contributing code to the project. On the other
+hand, respecting these guidelines will lead to uniform and more easily
+maintainable code and consequently we encourage everyone to follow
+them.
+
+* General
+** White space
+ - 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 (Why?)
+ - 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
+ - no (unnessary) empty lines
+** Other
+ - lines should not be longer than 80 characters
+ - do not use one charcter variables, except when it is a counter in a loop
+ - issues to be be fixed should be represented as:
+ #+begin_example
+ //FIXME(name_of_person): explanation what is wrong.
+ #+end_example
+ This makes looking and finxing for this types of problems easier
+ - things to do must be annotated with:
+ #+begin_example
+ //TODO(name_of_person): explain what to do
+ #+end_example
+ Don't be shy and put your name in there if this is something that
+ you expect will take a while.
+ - code that is old/broken should be removed (we have our version
+ control system so we can always go back to see how things were in
+ the past)
+ - functions should not contain more than ~30 lines. If you need
+ more: you probably need a new function anyway to separate
+ logical parts of the code.
+ - seperate code that outputs to file or console from rest of the code
+* R
+** Code
+ - Use the ~<-~ operator for assignments, not ~=~
+ - use codetools in R to check your functions
+** Documentation
+ We prefer that all documentation should be in roxygen2 format.
+* C/C++
+ - 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) *TODO: decide which one*
+ - both brackets of else statements should be on the same line
+ *Depends on previous item*
+ - always use {} in if clauses/for loops (even if there is only one
+ statement in the clause/loop
+ - make sure your code compiles without warnings/errors using
+ #+begin_example
+ gcc -wall
+ #+end_example
+* LaTeX
+* Configuring editors and IDEs to support the guidelines
+** Eclipse
+** Emacs
+ #+begin_src lisp
+ ;;; Trailing white space stuff
+ ;; Show trailing white space in orange
+ (setq-default show-trailing-whitespace t)
+ (set-face-background 'trailing-whitespace "orange1")
+ ;; nuke whitespaces when writing to a file
+ (add-hook 'before-save-hook 'whitespace-cleanup)
+ ;; Don't insert tabs when indenting regions (setq-default is used here
+ ;; to only overwrite this in buffers that do not have their own local
+ ;; values for this variable)
+ (setq-default indent-tabs-mode nil)
+
+ ;;; ESS mode (R, S, etc.)
+ (add-hook 'ess-mode-hook
+ (lambda ()
+ (auto-fill-mode t) ; Turn on auto-fill-mode
+ ; Set pdflatex as the default command for Sweave (default: texi2pdf)
+ (setq ess-swv-pdflatex-commands (quote ("pdflatex" "texi2pdf" "make")))
+ ))
+
+
+ ;;; C-mode:
+ ;; change C indentation style ("{" directly under "for" etc.)
+ (setq c-default-style "bsd"
+ c-basic-offset 4) ; Indentation of 4 spaces
+ ;; Turn on auto fill mode (max 80 columns)
+ (add-hook 'c-mode-common-hook 'auto-fill-mode)
+
+ ;;; LaTeX using AucTeX
+ (load "auctex.el" nil t t)
+ (add-hook 'LaTeX-mode-hook
+ (lambda()
+ 'turn-on-auto-fill ; Set max of 80 columns
+ ))
+
+ ;; Emacs' regular latex mode (when AucTeX isn't present)
+ (add-hook 'latex-mode-hook 'turn-on-reftex)
+ (add-hook 'latex-mode-hook 'turn-on-auto-fill)
+ #+end_src
More information about the Genabel-commits
mailing list