Menu
▾
▴
[Equanda-svn-commit] SF.net SVN: equanda:[1194] trunk
|
From: <tri...@us...> - 2010-01-21 09:35:12
|
Revision: 1194
http://equanda.svn.sourceforge.net/equanda/?rev=1194&view=rev
Author: triathlon98
Date: 2010-01-21 09:34:51 +0000 (Thu, 21 Jan 2010)
Log Message:
-----------
EQ-369 convert some stuff to docbook (lots to go)
Modified Paths:
--------------
trunk/pom.xml
trunk/src/site/site.xml
Added Paths:
-----------
trunk/src/site/docbook/
trunk/src/site/docbook/codingstyle.xml
trunk/src/site/docbook/developers.xml
trunk/src/site/docbook/docbook.xml
Removed Paths:
-------------
trunk/src/site/wiki/developers.wiki
Modified: trunk/pom.xml
===================================================================
--- trunk/pom.xml 2010-01-21 09:10:22 UTC (rev 1193)
+++ trunk/pom.xml 2010-01-21 09:34:51 UTC (rev 1194)
@@ -187,14 +187,26 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
- <!--<version>2.0-beta-7</version>-->
+ <version>2.0.1</version>
<dependencies>
<dependency>
+ <groupId>org.apache.maven.doxia</groupId>
+ <artifactId>doxia-module-docbook-simple</artifactId>
+ <version>1.0</version>
+ </dependency>
+ </dependencies>
+ <!--
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <!++<version>2.0-beta-7</version>++>
+ <dependencies>
+ <dependency>
<groupId>org.staticwiki</groupId>
<artifactId>staticwiki-site-plugin</artifactId>
<version>${staticwiki-release-version}</version>
</dependency>
</dependencies>
+ -->
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
@@ -502,11 +514,13 @@
<artifactId>joda-time</artifactId>
<version>1.5.2</version>
</dependency>
+ <!--
<dependency>
<groupId>org.staticwiki</groupId>
<artifactId>staticwiki-renderer</artifactId>
<version>${staticwiki-release-version}</version>
</dependency>
+ -->
<dependency>
<groupId>org.apache.maven.reporting</groupId>
<artifactId>maven-reporting-api</artifactId>
@@ -619,7 +633,9 @@
<properties>
<tapestry-release-version>5.1.0.5</tapestry-release-version>
<chenillekit-version>1.0.0</chenillekit-version>
+ <!--
<staticwiki-release-version>0.9.1-SNAPSHOT</staticwiki-release-version>
+ -->
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
Added: trunk/src/site/docbook/codingstyle.xml
===================================================================
--- trunk/src/site/docbook/codingstyle.xml (rev 0)
+++ trunk/src/site/docbook/codingstyle.xml 2010-01-21 09:34:51 UTC (rev 1194)
@@ -0,0 +1,347 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<!--
+ ~ This file is part of Geomajas, a component framework for building
+ ~ rich Internet applications (RIA) with sophisticated capabilities for the
+ ~ display, analysis and management of geographic information.
+ ~ It is a building block that allows developers to add maps
+ ~ and other geographic data capabilities to their web applications.
+ ~
+ ~ Copyright 2008-2010 Geosparc, http://www.geosparc.com, Belgium
+ ~
+ ~ This program is free software: you can redistribute it and/or modify
+ ~ it under the terms of the GNU Affero General Public License as
+ ~ published by the Free Software Foundation, either version 3 of the
+ ~ License, or (at your option) any later version.
+ ~
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ ~ GNU Affero General Public License for more details.
+ ~
+ ~ You should have received a copy of the GNU Affero General Public License
+ ~ along with this program. If not, see <http://www.gnu.org/licenses/>.
+ -->
+<article id="release" lang="en">
+ <title>Coding quality and style</title>
+
+ <toc />
+
+ <!--
+References
+- http://maven.apache.org/developers/conventions/code.html
+- http://docs.jboss.org/process-guide/en/html/coding.html
+- http://equanda.org/developers.html
+- http://svn.collab.net/repos/svn/trunk/www/hacking.html
+- http://java.sun.com/docs/codeconv/
+- http://geosoft.no/development/javastyle.html (!)
+- http://192.220.96.201/essays/java-style/single-page.html
+- http://gee.cs.oswego.edu/dl/html/javaCodingStd.html
+- http://www.ambysoft.com/essays/javaCodingStandards.html
+- http://docs.codehaus.org/display/GEOT/5+Project+Conventions
+-->
+
+ <para>As a general note, the coding style and naming conventions should be
+ adhered to. Some parts are even checked by the checkstyle maven plugin.
+ However, deviations are always allowed when this enhances code readability
+ (but only when checkstyle accepts it, otherwise the build will fail).</para>
+
+ <para>You can configure a formatter to apply this style in your favourite
+ IDE (see also at the bottom). You can be liberal on applying this on new
+ code, but be prudent when applying these to the existing code base. Code
+ style changes make revision changes a lot more difficult and should thus be
+ limited. If there is a need to reformat existing code, then this should be
+ done in a separate commit.</para>
+
+ <section>
+ <title>Class, method and variable names</title>
+
+ <para>Rules</para>
+
+ <itemizedlist>
+ <listitem>Use meaningful names. Especially class and method names should
+ explain their purpose.</listitem>
+
+ <listitem>For class, method and (non-static) variable names, use
+ camelCase to separate the words, not underscores. For abbreviations,
+ capitalize he first letter, lower case for the others.</listitem>
+
+ <listitem>Class names start with a capital, for example
+ "EquandaException".</listitem>
+
+ <listitem>Method and (non-static) variable names start lower case, for
+ example "getMessage".</listitem>
+
+ <listitem>All static variables should have capitalized names with words
+ separated by underscores.</listitem>
+
+ <listitem>Package names are all lower case and should be
+ singular.</listitem>
+
+ <listitem>Use getXxx/setXxx/isXxx.</listitem>
+
+ <listitem>Abbreviations and acronyms should not be uppercase when used
+ as name (for example, use "exportHtml()").</listitem>
+
+ <listitem>All names should be written in English.</listitem>
+
+ <listitem>The terms get/set must be used where an attribute is accessed
+ directly.</listitem>
+
+ <listitem>"is" prefix should be used for boolean variables and methods.
+ In some cases, when this is more readable, "has", "can" or "should" can
+ also be used as prefix.</listitem>
+
+ <listitem>Complement names must be used for complement entities. These
+ include get/set, add/remove, create/destroy, start/stop, insert/delete,
+ increment/decrement, old/new, begin/end, first/last, up/down, min/max,
+ next/previous, old/new, open/close, show/hide, suspend/resume,
+ etc.</listitem>
+
+ <listitem>Exception classes should be suffixed with
+ Exception.</listitem>
+ </itemizedlist>
+
+ <para>Recommendations</para>
+
+ <itemizedlist>
+ <listitem>Usually class names are nouns and method names are
+ verbs.</listitem>
+
+ <listitem>Generic variables should have the same name as their
+ type.</listitem>
+
+ <listitem>Variables with a large scope should have long names, variables
+ with a small scope can have short names. Scratch variables used for
+ temporary storage or indices are best kept short. A programmer reading
+ such variables should be able to assume that its value is not used
+ outside a few lines of code. Common scratch variables for integers are
+ i, j, k, m, n and for characters c and d.</listitem>
+
+ <listitem>The name of the object is implicit, and should be avoided in a
+ method name. For example, use "line.getLength()" instead of
+ "line.getLineLength()". The latter might seem natural in the class
+ declaration, but proves superfluous in use, as shown in the
+ example.</listitem>
+
+ <listitem>The term compute can be used in methods where something is
+ computed.</listitem>
+
+ <listitem>The term find can be used in methods where something is looked
+ up.</listitem>
+
+ <listitem>The term initialize can be used where an object or a concept
+ is established.</listitem>
+
+ <listitem>Plural form should be used on names representing a collection
+ of objects.</listitem>
+
+ <listitem>Negated boolean variable names must be avoided.</listitem>
+
+ <listitem>Default interface implementations can be prefixed by Default.
+ However, if it is not expected that there will even be another
+ implementation, it can be a lot more natural to suffix with "Impl"
+ instead.</listitem>
+
+ <listitem>Singleton classes should return their sole instance through
+ method getInstance(), should have a private constructor and be declared
+ final.</listitem>
+
+ <listitem>Functions (methods returning an object) should be named after
+ what they return and procedures (void methods) after what they
+ do.</listitem>
+ </itemizedlist>
+
+ <section><title>Comment</title>Each file should have the correct copyright
+ notice at the start of the file. <programlisting>/**
+ * This file is part of the equanda project.
+ *
+ * The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at http://www.mozilla.org/MPL/
+ *
+ * Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF
+ * ANY KIND, either express or implied. See the License for the specific language governing rights and
+ * limitations under the License.
+ *
+ * Alternatively, the contents of this file may be used under the terms of
+ * either the GNU General Public License Version 2 or later (the "GPL"), or
+ * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
+ * in which case the provisions of the GPL or the LGPL are applicable instead
+ * of those above. If you wish to allow use of your version of this file only
+ * under the terms of either the GPL or the LGPL, and not to allow others to
+ * use your version of this file under the terms of the MPL, indicate your
+ * decision by deleting the provisions above and replace them with the notice
+ * and other provisions required by the GPL or the LGPL. If you do not delete
+ * the provisions above, a recipient may use your version of this file under
+ * the terms of any one of the MPL, the GPL or the LGPL.
+ */</programlisting><itemizedlist>
+ <listitem>The copyright message should be at the top of the
+ file.</listitem>
+
+ <listitem>Each class and interface should have class comments
+ indicating the purpose of the class.</listitem>
+
+ <listitem>Public methods should be commented if the meaning is not
+ entirely clear from method and parameter names (is it ever?). When the
+ method overrides or implements a method, then repeating the javadoc is
+ not needed (it is recommended to us "@inheritedDoc").</listitem>
+
+ <listitem>Comments in the code are recommended when they explain a
+ block of code or when they explain why things are done in a certain
+ way. Repeating the code in human readable wording is
+ wasteful.</listitem>
+
+ <listitem>Use "@todo" comments to indicate shortcuts or hacks which
+ should be fixed. Better still is just to do it right and not have the
+ shortcut.</listitem>
+
+ <listitem>All comments should be written in English.</listitem>
+
+ <listitem>Comments should be indented relative to their position in
+ the code.</listitem>
+
+ <listitem>
+ <para>Javadoc comments should be active, not descriptive (for
+ example on method "getXxx()" the comment could be "Get xxx").</para>
+ </listitem>
+ </itemizedlist></section>
+
+ <section>
+ <title>Claim your code</title>
+
+ <para>Be proud of your code and take responsibility of your changes.
+ When making any kind of significant changes (not for reformatting,
+ fixing typing errors or renaming), add your full name (optionally
+ including e-mail link) at the bottom of the authors list in the class
+ comments.</para>
+ </section>
+
+ <section>
+ <title>Code layout</title>
+
+ <para>See the example below</para>
+
+ <programlisting>/**
+ * This file is part of the equanda project.
+ *
+ * The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at http://www.mozilla.org/MPL/
+ *
+ * Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF
+ * ANY KIND, either express or implied. See the License for the specific language governing rights and
+ * limitations under the License.
+ *
+ * Alternatively, the contents of this file may be used under the terms of
+ * either the GNU General Public License Version 2 or later (the "GPL"), or
+ * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
+ * in which case the provisions of the GPL or the LGPL are applicable instead
+ * of those above. If you wish to allow use of your version of this file only
+ * under the terms of either the GPL or the LGPL, and not to allow others to
+ * use your version of this file under the terms of the MPL, indicate your
+ * decision by deleting the provisions above and replace them with the notice
+ * and other provisions required by the GPL or the LGPL. If you do not delete
+ * the provisions above, a recipient may use your version of this file under
+ * the terms of any one of the MPL, the GPL or the LGPL.
+ */
+
+package org.equanda.bladibla;
+
+/**
+ * Page for importing/updating a portfolio from one of a selection of formats.
+ *
+ * @author <a href="mailto:au...@em...">Author's name</a>
+ * @author Another Author's Name
+ */
+@Annotation( param1 = "value1", param2 = "value2" )
+public class Foo
+ implements Serializable
+{
+ int[] x = new int[] { 1, 3, 5, 6, 7, 87, 1213, 2 };
+
+ /**
+ * Do something
+ *
+ * @param x some data
+ * @param y more data
+ */
+ public void foo( int x, int y )
+ throws Exception
+ {
+ for ( int i = 0; i < x ; i++ )
+ {
+ y += ( y ^ 0x123 ) << 2;
+ }
+ do
+ {
+ try
+ {
+ if ( 0 < x && x < 10 )
+ {
+ while ( x != y )
+ {
+ x = f( x * 3 + 5 );
+ }
+ }
+ else
+ {
+ synchronized ( this )
+ {
+ switch ( e.getCode() )
+ {
+ //...
+ }
+ }
+ }
+ }
+ catch ( MyException e )
+ {}
+ finally
+ {
+ int[] arr = (int[]) g( y );
+ x = y >= 0 ? arr[ y ] : -1;
+ }
+ }
+ while ( true );
+ }
+}</programlisting>
+
+ <para>The codingstyle is optimized for readability and thus uses a lot
+ of whitespace both horizontally as vertically.</para>
+
+ <itemizedlist>
+ <listitem>The code is written with the right margin at 120 characters
+ and lines should not be longer than that if possible.</listitem>
+
+ <listitem>All indents should be done using four spaces, no tabs
+ !</listitem>
+
+ <listitem>Braces are always on separate lines. The only exception is
+ for empty blocks and single line ifs and for/while loops.</listitem>
+
+ <listitem>Always use spaces inside brackets.</listitem>
+
+ <listitem>Spaces around operators.</listitem>
+
+ <listitem>No wildcards allowed on import statements.</listitem>
+
+ <listitem>Always use braces when the body is not on the same line as
+ the if, for, while, do-while.</listitem>
+
+ <listitem>Array specifiers must be attached to the type not the
+ variable.</listitem>
+
+ <listitem>Class variables should never be declared public.</listitem>
+
+ <listitem>Logical units within a block should be separated by one
+ blank line.</listitem>
+ </itemizedlist>
+
+ <para>We have an <ulink url="equanda.xml">IntelliJ IDEA</ulink>
+ formatter which can be used. However, be careful not to change the
+ entire formatting of a class.</para>
+ </section>
+ </section>
+</article>
Added: trunk/src/site/docbook/developers.xml
===================================================================
--- trunk/src/site/docbook/developers.xml (rev 0)
+++ trunk/src/site/docbook/developers.xml 2010-01-21 09:34:51 UTC (rev 1194)
@@ -0,0 +1,293 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<!--
+ ~ This file is part of Geomajas, a component framework for building
+ ~ rich Internet applications (RIA) with sophisticated capabilities for the
+ ~ display, analysis and management of geographic information.
+ ~ It is a building block that allows developers to add maps
+ ~ and other geographic data capabilities to their web applications.
+ ~
+ ~ Copyright 2008-2010 Geosparc, http://www.geosparc.com, Belgium
+ ~
+ ~ This program is free software: you can redistribute it and/or modify
+ ~ it under the terms of the GNU Affero General Public License as
+ ~ published by the Free Software Foundation, either version 3 of the
+ ~ License, or (at your option) any later version.
+ ~
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ ~ GNU Affero General Public License for more details.
+ ~
+ ~ You should have received a copy of the GNU Affero General Public License
+ ~ along with this program. If not, see <http://www.gnu.org/licenses/>.
+ -->
+<article id="release" lang="en">
+ <title>Developers information</title>
+
+ <toc />
+
+ <section>
+ <title>maven targets, profiles, variables</title>
+
+ <para>There are two main ways to install, either just compiling, running
+ the simple tests and installing, or running the full testsuite which does
+ integration tests by deploying some sample stuff into a jboss
+ instance.</para>
+
+ <para>You can choose by using one of the following targets.</para>
+
+ <programlisting>mvn install
+mvn -Dfulltest install
+</programlisting>
+
+ <para>To be able to run the full test suite, you need to include a profile
+ in your maven local settings (.m2/settings.xml).</para>
+
+ <programlisting><settings>
+ <profiles>
+ <profile>
+ <id>dev-joachim</id>
+ <properties>
+ <!-- selenium properties-->
+ <firefox.path>firefox /usr/lib/firefox/firefox-bin</firefox.path>
+
+ <equanda.db.url>jdbc:firebirdsql:localhost/3050:/home/joachim/data/equanda.fdb</equanda.db.url>
+ <equanda.db.login>sysdba</equanda.db.login>
+ <equanda.db.password>masterkey</equanda.db.password>
+ <equanda.db.location>/home/joachim/data/equanda.fdb</equanda.db.location>
+ <equanda.db.empty>/home/joachim/data/equanda-empty.fdb</equanda.db.empty>
+ <equanda.cargo.wait>true</equanda.cargo.wait>
+ <!-- jboss properties-->
+ <equanda.jboss.home>/home/joachim/java/equandajboss</equanda.jboss.home>
+ <equanda.jboss.config>equanda</equanda.jboss.config>
+ <equanda.jboss.host>localhost</equanda.jboss.host>
+ <equanda.jboss.port>8080</equanda.jboss.port>
+ <equanda.jboss.jvmargs>
+ -server -Xms256m -Xmx382m -XX:MaxPermSize=128m -Dsun.net.inetaddr.ttl=15
+ -Dsun.rmi.dgc.client.gcInterval=3600000
+ -Dsun.rmi.dgc.server.gcInterval=3600000
+ </equanda.jboss.jvmargs>
+ <equanda.jboss.logging>medium</equanda.jboss.logging>
+
+ </properties>
+ </profile>
+ </profiles>
+ <activeProfiles>
+ <activeProfile>dev-joachim</activeProfile>
+ </activeProfiles>
+
+ <pluginGroups>
+ <pluginGroup>org.equanda</pluginGroup>
+ </pluginGroups>
+
+</settings></programlisting>
+ </section>
+
+ <section><title>Documentation</title><para>All documentation is written in
+ docbook format to allow both PDF and HTML output formats. </para>To generate
+ the project site, use <programlisting>mvn site</programlisting><para>For
+ editing the docbook files, we recommend using <ulink
+ url="http://www.xmlmind.com/xmleditor/">XMLMind</ulink>. The personal
+ version is free and can (at the time of writing) be used for editing open
+ source documentation. </para><para>The docbook files are currently formatted
+ using XMLMind. When using another tool for editing, please keep the current
+ formatting to assure diffs remain usable. </para></section>
+
+ <section>
+ <title>subversion, commits</title>
+
+ <para>All SVN commits should include the JIRA issue number at the start of
+ the commit message, and a short description of the work done. The JIRA
+ issue number allows linking the commits with the issues (as can be seen in
+ JIRA), the short message allows persons to know what is happening without
+ referring to JIRA. The only times JIRA issue number are not needed is for
+ making "obvious" changes like fixing typos.</para>
+
+ <para>Commits should be grouped by issue as much as possible/sensible
+ (better two commits than one commit for fixing two issues, better one
+ commit of five files than five commits of one file (for one
+ issue)).</para>
+
+ <para>Development of the "latest-and-greatest" version happens in
+ "trunk".</para>
+
+ <para>When a release is cut, a tag with the release version as name is
+ created. The release should be built from the tagged files.</para>
+
+ <para>After each commit, the system should still compile and all test
+ cases should still succeed. There is a continuous integration engine
+ (Hudson) which verifies this and sends messages to the developers mailing
+ list on failures.</para>
+ </section>
+
+ <section>
+ <title>Coding</title>
+
+ <para>Note that details about coding style and naming are on the <ulink
+ url="codingstyle.html">coding style</ulink> page.</para>
+
+ <section>
+ <title>Logging</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>For debug level messages, always use
+ <code>isDebugEnabled()</code>.</para>
+ </listitem>
+
+ <listitem>all logging is done through log4j, logger is created using
+ <programlisting>private static final Logger log = Logger.getLogger( ContainingClassName.class );</programlisting></listitem>
+
+ <listitem>logging levels<table>
+ <title>logging levels</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry align="center">log level</entry>
+
+ <entry align="center">default on</entry>
+
+ <entry>use</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>ERROR</entry>
+
+ <entry>yes</entry>
+
+ <entry>major problems, should always be visible in logs and
+ are likely to require action from a person (to fix the
+ condition or assure it does not happen again). Indicates
+ that something is seriously wrong.</entry>
+ </row>
+
+ <row>
+ <entry>WARN</entry>
+
+ <entry>yes</entry>
+
+ <entry>warning about potential problems. Should always be
+ visible in logs and a person will probably need to assess
+ whether this is harmless or should be treated as an
+ error.</entry>
+ </row>
+
+ <row>
+ <entry>INFO</entry>
+
+ <entry>yes</entry>
+
+ <entry>important information. You can assume this level is
+ on in production, so it should be carefully considered
+ whether this level is appropriate. In general only used to
+ indicate service status (started, stopped).</entry>
+ </row>
+
+ <row>
+ <entry>DEBUG</entry>
+
+ <entry>no</entry>
+
+ <entry>logging information which is detailed enough to know
+ what is happening in the system, without flooding the
+ logs.</entry>
+ </row>
+
+ <row>
+ <entry>TRACE</entry>
+
+ <entry>no</entry>
+
+ <entry>very detailed logging, probably only making sense to
+ the developer of the code.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></listitem>
+
+ <listitem>When an exception is caught and (another exception) thrown
+ you should not log the exception. You should however include the cause
+ in the newly thrown exception.</listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Unit testing</title>
+
+ <para>Unit testing: At least each class implementing the public API
+ should have a unit test, testing all methods. For testing JUnit is
+ used.</para>
+
+ <itemizedlist>
+ <listitem>Advantages of unit testing: <itemizedlist>
+ <listitem>
+ <para>Capturing a <ulink
+ url="http://jira.geomajas.org/">JIRA</ulink> bug report in a
+ reproducible manner.</para>
+ </listitem>
+
+ <listitem>Allowing you to specify exactly the behaviour you want,
+ before you start coding.</listitem>
+ </itemizedlist></listitem>
+
+ <listitem>How unit testing should be done: <itemizedlist>
+ <listitem>If you are testing
+ src/main/java/org/geomajas/ToBeTestedClass.java, create a class
+ src/test/java/org/geomajas/ToBeTestedClassTest.java. Actual test
+ methods have a name starting with "test". The class itself should
+ extend jnit.framework.TestCase.</listitem>
+
+ <listitem>
+ <para>The test will automatically be run when running "<code>mvn
+ install</code>".</para>
+ </listitem>
+ </itemizedlist></listitem>
+
+ <listitem>Integration tests should also be provided. These can also be
+ used for testing the user interface (thanks to selenium).</listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Exception handling</title>
+
+ <para>*Never* throw away exception, either log them or throw them again
+ (possibly wrapped). Do not log and throw, this only clutters log files
+ with duplicate exceptions.</para>
+
+ <para>Do not wrap exceptions unnecessarily (so no
+ <code>EquandaException</code> caused by a <code>EquandaException</code>)
+ unless you add additional information in the message.</para>
+
+ <para>When wrapping an exception, always include the cause.</para>
+ </section>
+
+ <section>
+ <title>Refactoring</title>
+
+ <para>Changes in the (public) API use a "deprecate, then remove" cycle.
+ It should be marked "deprecated" in at least one minor version before it
+ can be removed in the next major version.</para>
+ </section>
+
+ <section>
+ <title>File encoding</title>
+
+ <para>All source files, including .properties files should use UTF-8
+ encoding.</para>
+ </section>
+
+ <section>
+ <title>Other</title>
+
+ <para>For the directory structure and file locations, we follow standard
+ maven conventions (see <ulink
+ url="http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html">http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html</ulink>).</para>
+ </section>
+ </section>
+</article>
Added: trunk/src/site/docbook/docbook.xml
===================================================================
--- trunk/src/site/docbook/docbook.xml (rev 0)
+++ trunk/src/site/docbook/docbook.xml 2010-01-21 09:34:51 UTC (rev 1194)
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<article id="docbook" lang="en">
+ <title>Page title</title>
+ <toc></toc>
+<para>
+<note>
+<para><emphasis>warning</emphasis> : this documentation is still somewhat incomplete. We are working hard to improve both the feature set and the documentation. So do have a browse around, but definitely come back later to see how things evolve.</para>
+</note>
+ </para>
+
+<section><title>Section</title>
+<para>
+A sample paragraph.
+</para>
+ </section>
+
+</article>
Modified: trunk/src/site/site.xml
===================================================================
--- trunk/src/site/site.xml 2010-01-21 09:10:22 UTC (rev 1193)
+++ trunk/src/site/site.xml 2010-01-21 09:34:51 UTC (rev 1194)
@@ -28,6 +28,7 @@
<item name="Configuration" href="config.html"/>
<item name="Domain Model" href="dm.html"/>
<item name="Developers" href="developers.html"/>
+ <item name="Coding Style" href="codingstyle.html"/>
</item>
<item name="Roadmap" href="roadmap.html"/>
<item name="License" href="license.html"/>
Deleted: trunk/src/site/wiki/developers.wiki
===================================================================
--- trunk/src/site/wiki/developers.wiki 2010-01-21 09:10:22 UTC (rev 1193)
+++ trunk/src/site/wiki/developers.wiki 2010-01-21 09:34:51 UTC (rev 1194)
@@ -1,162 +0,0 @@
-h1. Developers information
-
-h2. maven targets, profiles, variables
-
-There are two main ways to install, either just compiling, running the simple tests and installing, or running the full testsuite which does integration tests by deploying some sample stuff into a jboss instance.
-You can choose by using one of the following targets.
-{code}
-mvn install
-mvn -Dfulltest install
-{code}
-
-To be able to run the full test suite, you need to include a profile in your maven local settings (.m2/settings.xml).
-{code}
-<settings>
- <profiles>
- <profile>
- <id>dev-joachim</id>
- <properties>
- <!-- selenium properties-->
- <firefox.path>firefox /usr/lib/firefox/firefox-bin</firefox.path>
-
- <equanda.db.url>jdbc:firebirdsql:localhost/3050:/home/joachim/data/equanda.fdb</equanda.db.url>
- <equanda.db.login>sysdba</equanda.db.login>
- <equanda.db.password>masterkey</equanda.db.password>
- <equanda.db.location>/home/joachim/data/equanda.fdb</equanda.db.location>
- <equanda.db.empty>/home/joachim/data/equanda-empty.fdb</equanda.db.empty>
- <equanda.cargo.wait>true</equanda.cargo.wait>
- <!-- jboss properties-->
- <equanda.jboss.home>/home/joachim/java/equandajboss</equanda.jboss.home>
- <equanda.jboss.config>equanda</equanda.jboss.config>
- <equanda.jboss.host>localhost</equanda.jboss.host>
- <equanda.jboss.port>8080</equanda.jboss.port>
- <equanda.jboss.jvmargs>
- -server -Xms256m -Xmx382m -XX:MaxPermSize=128m -Dsun.net.inetaddr.ttl=15
- -Dsun.rmi.dgc.client.gcInterval=3600000
- -Dsun.rmi.dgc.server.gcInterval=3600000
- </equanda.jboss.jvmargs>
- <equanda.jboss.logging>medium</equanda.jboss.logging>
-
- </properties>
- </profile>
- </profiles>
- <activeProfiles>
- <activeProfile>dev-joachim</activeProfile>
- </activeProfiles>
-
- <pluginGroups>
- <pluginGroup>org.equanda</pluginGroup>
- </pluginGroups>
-
-</settings>
-{code}
-
-h2. Coding quality and style
-
-h3. Class, method and variable names
-
-Use meaningful names. Especially class and method names should explain their purpose. Use standard java camelcase conventions.
-
-h3. Comments
-
-- Each file should have a copyright notice at the start of the file.
-- Each class should have class comments indicating the purpose of the class and the authors.
-- Public methods should be commented if the meaning is not entirely clear from method and parameter names (is it ever?). When the method overrides or implements a method, then repeating the javadoc is not needed.
-- Comments in the code are recommended when they explain a block of code or when they explain why things are done in a certain way. Repeating the code in human readable wording is wasteful.
-- Use "@todo" comments to indicate shortcuts or hacks which should be fixed. Better still is just to do it right and not have the shortcut.
-- When inserting debug statements, always put them inside a "log.isDebugEnabled()" test.
-
-h3. Claim your code
-
-Be proud of your code and take responsibility of your changes. When making any kind of significant changes (not for reformatting, fixing typing errors or renaming), add your name and e-mail address at the bottom of the authors list in the class comments.
-
-h3. Coding style
-
-In equanda we use a coding style which prefers easy reading above displaying a lot of information. Most of the features should be clear in the following piece of code.
-{code}
-/**
- * This file is part of the equanda project.
- *
- * The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at http://www.mozilla.org/MPL/
- *
- * Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF
- * ANY KIND, either express or implied. See the License for the specific language governing rights and
- * limitations under the License.
- *
- * Alternatively, the contents of this file may be used under the terms of
- * either the GNU General Public License Version 2 or later (the "GPL"), or
- * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
- * in which case the provisions of the GPL or the LGPL are applicable instead
- * of those above. If you wish to allow use of your version of this file only
- * under the terms of either the GPL or the LGPL, and not to allow others to
- * use your version of this file under the terms of the MPL, indicate your
- * decision by deleting the provisions above and replace them with the notice
- * and other provisions required by the GPL or the LGPL. If you do not delete
- * the provisions above, a recipient may use your version of this file under
- * the terms of any one of the MPL, the GPL or the LGPL.
- */
-
-package org.equanda.bladibla;
-
-/**
- * Page for importing/updating a portfolio from one of a selection of formats.
- *
- * @author <a href="mailto:au...@em...">Author's name</a>
- */
-@Annotation( param1 = "value1", param2 = "value2" )
-public class Foo
- implements Serializable
-{
- int[] x = new int[] { 1, 3, 5, 6, 7, 87, 1213, 2 };
-
- /**
- * Do something
- *
- * @param x some data
- * @param y more data
- */
- public void foo( int x, int y )
- throws Exception
- {
- for ( int i = 0; i < x ; i++ )
- {
- y += ( y ^ 0x123 ) << 2;
- }
- do
- {
- try
- {
- if ( 0 < x && x < 10 )
- {
- while ( x != y )
- {
- x = f( x * 3 + 5 );
- }
- }
- else
- {
- synchronized ( this )
- {
- switch ( e.getCode() )
- {
- //...
- }
- }
- }
- }
- catch ( MyException e )
- {}
- finally
- {
- int[] arr = (int[]) g( y );
- x = y >= 0 ? arr[ y ] : -1;
- }
- }
- while ( true );
- }
-}
-{code}
-The code is written with the right margin at 120 characters and lines should not be longer than that if possible.
-An indentation is 4 spaces, tabs should not be used.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
