Author: vsiveton
Date: Thu Jul 3 13:30:29 2008
New Revision: 673792
URL: http://svn.apache.org/viewvc?rev=673792&view=rev
Log:
MNGSITE-55: Write a document about POM code style
o reorganized code style and conventions
Added:
maven/site/trunk/src/site/apt/developers/conventions/
maven/site/trunk/src/site/apt/developers/conventions/code.apt (with props)
Modified:
maven/site/trunk/src/site/apt/developers/index.apt
maven/site/trunk/src/site/apt/guides/development/guide-helping.apt
maven/site/trunk/src/site/apt/guides/development/guide-m2-development.apt
Added: maven/site/trunk/src/site/apt/developers/conventions/code.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/developers/conventions/code.apt?rev=673792&view=auto
==============================================================================
--- maven/site/trunk/src/site/apt/developers/conventions/code.apt (added)
+++ maven/site/trunk/src/site/apt/developers/conventions/code.apt Thu Jul 3
13:30:29 2008
@@ -0,0 +1,246 @@
+ ------
+ Maven Code Style And Code Convention
+ ------
+ Vincent Siveton
+ ------
+ 2008-07-03
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+Maven Code Style And Code Convention
+
+ This document describes how developers and contributors should write code.
The reasoning of these styles and conventions is
+ mainly for consistency, readability and maintainability reasons.
+
+* Generic Code Style And Convention
+
+ All working files (java, xml, others) should respect the following
conventions:
+
+ * <<License Header>>: Always add the current
{{{http://www.apache.org/legal/src-headers.html#headers}ASF license header}}
+ in all versionned files.
+
+ * <<Trailing Whitespaces>>: Remove all trailing whitespaces. If your are an
Eclipse user, you could use the
+ {{{http://andrei.gmxhome.de/anyedit/}Anyedit Eclipse Plugin}}.
+
+~~ * Using SVN properties like \$Id: \$ => Is it a wanted goal for all files
like java or apt?
+ []
+
+ and the following style:
+
+ * <<Indentation>>: Always use 2 space indents and <<never>> use tabs!
+
+ * <<Line wrapping>>: Always use a 120-column line width.
+
+ []
+
+* {Java}
+
+** {Java Code Style}
+
+ The Maven style for Java is mainly:
+
+ * <<White space>>: One space after control statements and between arguments
(i.e. <<<if ( foo )>>> instead of
+ <<<if(foo)>>>), <<<myFunc( foo, bar, baz )>>> instead of
<<<myFunc(foo,bar,baz)>>>).
+ No spaces after methods names (i.e. <<<void myMethod(), myMethod( "foo"
)>>>)
+
+ * <<Blocks>>: Always enclose with a new line brace.
+
+ * <<Indentation>>: Always use 2 space indents, unless you're wrapping a line
in which case you should indent 4 spaces
+ or indent to line up arguments.
+
+ * <<Line wrapping>>: Always use a 120-column line width for Java code and
Javadoc.
+
+ []
+
+ The following sections show how to set up the code style for Maven in IDEA
and Eclipse.
+ It is strongly preferred that patches use this style before they are applied.
+
+*** IntelliJ IDEA 4.5+
+
+ Download
<<<{{{../../developers/maven-idea-codestyle.xml}maven-idea-codestyle.xml}}>>>
and copy it to
+ <<<~/.IntelliJIDEA/config/codestyles>>> then restart IDEA. On Windows, try
+ <<<C:\Documents and Settings\<username>\.IntelliJIDEA\config\codestyles>>>
+
+ After this, restart IDEA and open the settings to select the new code style.
+
+*** Eclipse 3.2+
+
+ Download
<<<{{{../../developers/maven-eclipse-codestyle.xml}maven-eclipse-codestyle.xml}}>>>.
+
+ After this, select Window \> Preferences, and open up the configuration for
Java \> Code
+ Style \> Code Formatter. Click on the button labeled Import... and select the
file you
+ downloaded. Give the style a name, and click OK.
+
+** {Java Code Convention}
+
+ For consistency reasons, our Java code convention is mainly:
+
+ * <<Naming>>: Constants (i.e. static final members) values should always be
in upper case.
+ Using short, descriptive names for classes and methods.
+
+ * <<Organization>>: Avoid using a lot of public inner classes. Prefer
interfaces instead of default implementation.
+
+ * <<Modifier>>: Avoid using final modifier on all member variables and
arguments.
+ Prefer using private or protected member instead of public member.
+
+ * <<Exceptions>>: Throw meaningful exceptions to makes debugging and testing
more easy.
+
+ * <<Documentation>>: Document public interfaces well, i.e. all non-trivial
public and
+ protected functions should include Javadoc that indicates what it does.
+ <<Note>>: it is an ongoing convention for the Maven Team.
+
+ * <<Testing>>: All non-trivial public classes should include corresponding
unit or IT tests.
+
+ []
+
+* {XML}
+
+** {XML Code Style}
+
+ The Maven style for XML files is mainly:
+
+ * <<Indentation>>: Always use 2 space indents, unless you're wrapping a new
XML tags line in which case you should
+ indent 4 spaces.
+
+ * <<Line Breaks>>: Always use a new line with indentation for complex XML
types and no line break for simple XML
+ types. Always use a new line to separate XML sections or blocks, for instance:
+
++-----+
+<aTag>
+ <simpleType>This is a simple type</simpleType>
+
+ <complexType>
+ <simpleType>This is a complex type</simpleType>
+ </complexType>
+</aTag>
++-----+
+
+ In some cases, adding comments could improve the readability of blocks, for
instance:
+
++-----+
+ <!-- Simple XML documentation
-->
++-----+
+
+ or
+
++-----+
+ <!--
====================================================================== -->
+ <!-- Block documentation
-->
+ <!--
====================================================================== -->
++-----+
+
+ []
+
+** {Generic XML Code Convention}
+
+ No generic code convention exists yet for XML files.
+
+** {POM Code Convention}
+
+ The team has
{{{http://www.nabble.com/-Proposal--Pom-Code-Style-(WAS-svn-commit%3A-r670264----maven-plugins-trunk-maven-site-plugin-pom.xml)-td18083228.html}voted}}
+ during the end of June 2008 to follow a specific POM convention to ordering
POM elements.
+ The consequence of this vote is that the
{{{http://maven.apache.org/ref/current/maven-model/maven.html}Maven project
descriptor}}
+ is <<no more>> consider as the reference for the ordering.
+
+ The following is the recommended ordering for all Maven POM files:
+
++-----+
+<project xmlns="http://maven.apache.org/POM/4.0.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd";>
+ <modelVersion/>
+
+ <parent/>
+
+ <groupId/>
+ <artifactId/>
+ <version/>
+ <packaging/>
+
+ <name/>
+ <description/>
+ <url/>
+ <inceptionYear/>
+ <organization/>
+ <licenses/>
+
+ <developers/>
+ <contributors/>
+
+ <mailingLists/>
+
+ <prerequisites/>
+
+ <modules/>
+
+ <scm/>
+ <issueManagement/>
+ <ciManagement/>
+ <distributionManagement/>
+
+ <properties/>
+
+ <dependencyManagement/>
+ <dependencies/>
+
+ <repositories/>
+ <pluginRepositories/>
+
+ <build/>
+
+ <reporting/>
+
+ <profiles/>
+</project>
++-----+
+
+ <<Comments>>:
+
+ [[1]] The \<project/\> element is always on one line.
+
+ [[2]] The blocks are voluntary separated by a new line to improve the
readingness.
+
+ [[3]] The dependencies in \<dependencies/\> and \<dependencyManagement/\>
tags have no specific ordering. Developers
+ are free to choose the ordering, but grouping dependencies by topics (like
groupId i.e. <<<org.apache.maven>>>) is a good practice.
+
+ []
+
+ <<Note>>: The team plans to create a Maven plugin with reorder and reformat
goals
+ (See {{{http://jira.codehaus.org/browse/MOJO-928}MOJO-928}}).
+
+** {XDOC Code Convention}
+
+ For consistency and readability reasons, XDOC files should respect:
+
+ * <<Metadata>>: Always specify metadata in the \<properties/\> tag.
+
+ * <<Sections>>: Always use a new line with indentation for \<section/\> tags.
+
+ []
+
+** {FML Code Convention}
+
+ For readability reasons, FML files should respect:
+
+ * <<FAQ>>: Always use a new line with indentation for \<faq/\> tags.
+
+ []
+
+~~ * {APT} Do we need any specific APT style/convention?
Propchange: maven/site/trunk/src/site/apt/developers/conventions/code.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/site/trunk/src/site/apt/developers/conventions/code.apt
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Modified: maven/site/trunk/src/site/apt/developers/index.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/developers/index.apt?rev=673792&r1=673791&r2=673792&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/developers/index.apt (original)
+++ maven/site/trunk/src/site/apt/developers/index.apt Thu Jul 3 13:30:29 2008
@@ -4,7 +4,7 @@
Vincent Siveton
Brett Porter
------
- October 2006
+ July 2008
------
~~ Licensed to the Apache Software Foundation (ASF) under one
@@ -44,6 +44,8 @@
* Source Repository for Maven
{{{../ref/2.0.9-SNAPSHOT/source-repository.html}2.0.x}}
or {{{../ref/2.1-SNAPSHOT/source-repository.html}2.1.x}}
+ []
+
* Committers Resources
** General Resources
@@ -54,16 +56,33 @@
* {{{./committer-settings.html}Committer Settings}}
+ []
+
+* Developers Conventions
+
+ There are a number of conventions used in the Maven projects, which
contributors and developers alike should follow for
+ consistency's sake.
+
+ * {{{./conventions/code.html}Maven Code Style And Convention}}
+
+ []
+
+ <<Note>>: If you cannot find your answers here, feel free to ask the
{{{mailto:[EMAIL PROTECTED] Developer List}}.
+
* Making Releases
* {{{./release/pmc-gpg-keys.html}Making GPG Keys}}
* {{{./release/releasing.html}Release Process}}
+ []
+
* Deploy Maven references
* {{{./website/deploy-maven-current-ref.html}Deploy Maven Current
References}}
+ []
+
* Others Resources
* {{{http://people.apache.org/~vgritsenko/stats/projects/maven.html}Maven
Web Stats}}
@@ -74,6 +93,8 @@
* {{{http://www.apache.org/foundation/}About the Apache Software Foundation}}
+ []
+
~~TODO: tasks as buttons?
~~TODO: de-dupe with existing documents in community
Modified: maven/site/trunk/src/site/apt/guides/development/guide-helping.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/development/guide-helping.apt?rev=673792&r1=673791&r2=673792&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/development/guide-helping.apt
(original)
+++ maven/site/trunk/src/site/apt/guides/development/guide-helping.apt Thu Jul
3 13:30:29 2008
@@ -4,9 +4,29 @@
Brett Porter
Jason van Zyl
------
- 12 October 2005
+ 2008-07-03
------
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
Guide to helping with Maven
As with any open source project, there are several ways you can help:
@@ -43,6 +63,8 @@
* You are giving back to a community that has given you software for free
+ []
+
How do I Join the Project?
Projects at Apache operate under a meritocracy, meaning those that the
developers notice participating to a
@@ -58,10 +80,12 @@
There are a number of conventions used in the project, which contributors
and developers alike should follow for
consistency's sake.
- * {{{./guide-m2-development.html#Maven_Code_Style} Code Style}}
+ * {{{../../developers/conventions/code.html}Maven Code Style And Convention}}
* {{{./guide-m2-development.html#Commit_Message_Template} Commit Message
Template}}
+ []
+
Resources for committers
* {{{http://www.apache.org/dev/} Developer Resources}}
@@ -76,5 +100,4 @@
* {{{http://wiki.apache.org/} Apache Wiki}}
-
-
+ []
Modified:
maven/site/trunk/src/site/apt/guides/development/guide-m2-development.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/development/guide-m2-development.apt?rev=673792&r1=673791&r2=673792&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/development/guide-m2-development.apt
(original)
+++ maven/site/trunk/src/site/apt/guides/development/guide-m2-development.apt
Thu Jul 3 13:30:29 2008
@@ -5,7 +5,7 @@
Trygve Laugstol
Brett Porter
------
- 28 June 2008
+ 2008-07-03
------
~~ Licensed to the Apache Software Foundation (ASF) under one
@@ -223,27 +223,6 @@
{{{http://www.apache.org/dev/version-control.html#https-svn}Committer
Subversion Access}}
document and you must set your svn client with this properties file :
{{{../../developers/svn-eol-style.txt}svn-eol-style.txt}}
-* {Maven Code Style}
-
- The following sections show how to set up the code style for Maven in IDEA
and Eclipse.
- It is strongly preferred that patches use this style before they are applied.
-
-** IntelliJ IDEA 4.5+
-
- Download
<<<{{{../../developers/maven-idea-codestyle.xml}maven-idea-codestyle.xml}}>>>
and copy it to
- <<<~/.IntelliJIDEA/config/codestyles>>> then restart IDEA. On Windows, try
- <<<C:\Documents and Settings\<username>\.IntelliJIDEA\config\codestyles>>>
-
- After this, restart IDEA and open the settings to select the new code style.
-
-** Eclipse 3.2+
-
- Download
<<<{{{../../developers/maven-eclipse-codestyle.xml}maven-eclipse-codestyle.xml}}>>>.
-
- After this, select Window \> Preferences, and open up the configuration for
Java \> Code
- Style \> Code Formatter. Click on the button labeled Import... and select the
file you
- downloaded. Give the style a name, and click OK.
-
* {Commit Message Template}
Commits should have a message that follows this template:
@@ -264,5 +243,3 @@
[MNG-1456] Added the foo to the bar
Submitted by: Baz Bazman
-----
-
-
