JanusWiki - Recent changes [en]

MediaWiki:Sidebar

2010-09-03T09:53:34Z

Coding Conventions

2010-09-03T07:39:43Z

← Older revision		Revision as of 07:39, 3 September 2010
Line 105:		Line 105:

	To quickly configure your Eclipse, you may import the following preferences:		To quickly configure your Eclipse, you may import the following preferences:
-	* ~~Eclipse~~ Galileo ~~Preferences~~	+	* Galileo: [[File:Preferences_Galileo.epf.gz]]

	= Related Pages =		= Related Pages =

	* [[Developper_Conventions\|Conventions and Guidelines for Developers]]		* [[Developper_Conventions\|Conventions and Guidelines for Developers]]

Javadoc Conventions

2010-09-03T07:39:09Z

← Older revision		Revision as of 07:39, 3 September 2010
(One intermediate revision not shown)
Line 47:		Line 47:

	To quickly configure your Eclipse, you may import the following preferences:		To quickly configure your Eclipse, you may import the following preferences:
-	* ~~Eclipse~~ Galileo ~~Preferences~~	+	* Galileo: [[File:Preferences_Galileo.epf.gz]]

File:Preferences Galileo.epf.gz

2010-09-03T07:37:31Z

uploaded "[[File:Preferences Galileo.epf.gz]]"

New page

FAQ

2010-09-02T19:36:49Z

← Older revision		Revision as of 19:36, 2 September 2010
Line 73:		Line 73:
	== What are the conventions and the guidelines for developers? ==		== What are the conventions and the guidelines for developers? ==

-	See [[~~Developper_Conventions~~\|Conventions and guidelines for developers]].	+	See [[Developer_Conventions\|Conventions and guidelines for developers]].

Developper Conventions

2010-09-02T19:36:08Z

moved [[Developper Conventions]] to [[Developer Conventions]]

New page

Developper Conventions

2010-09-02T19:35:01Z

← Older revision		Revision as of 19:35, 2 September 2010
Line 7:		Line 7:
	* [[Coding Conventions]]<br/>How to make Java code readable		* [[Coding Conventions]]<br/>How to make Java code readable
	* [[Javadoc Conventions]]<br/>How to write documentation comments, especially for API		* [[Javadoc Conventions]]<br/>How to write documentation comments, especially for API
-	* [[Graphic User Interface Conventions]]<br/>How to design a graphic user interface

Javadoc Conventions

2010-09-02T19:32:52Z

Created page with '= General = The specifications for the APIs are captured in the form of Javadoc comments on API packages, interfaces and classes, methods and constructors, and fields. The Java…'

New page

= General =

The specifications for the APIs are captured in the form of Javadoc comments on API packages, interfaces and classes, methods and constructors, and fields. The Javadoc tool (running the standard doclet) extracts these specifications and formats them into browsable form (HTML web pages) which become the reference section of the documentation set describing the Janus projects to ISVs. As a consequence, the bar is significantly higher for API Javadoc than for non-API. [http://java.sun.com/products/jdk/javadoc/writingapispecs/index.html Sun's Requirements for Writing Java API Specifications] deals with required semantic content of documentation comments for API specifications for the Java platform. All SeT project APIs should follow these conventions.

[http://java.sun.com/products/jdk/javadoc/writingdoccomments/index.html Sun's How to Write Doc Comments for Javadoc] contains style guide and tag conventions for documentation comments. These conventions lead to high-quality code and API documentation. All code written for the Janus projects should follow these conventions except as noted below.

= Additional Guidelines =

The Janus project has specific guidelines for package, class and interface comments. Each package, class and interface must start the following comment template:

<source lang="java5">
/**
* ${comment about this feature}
*
* ${generic parameter comments}
* @author ${full name 2} <${email 1}>
* @author ${full name 2} <${email 2}>
* @version $Name$ $Revision$ $Date$
* @mavengroupid $GroupId$
* @mavenartifactid $ArtifactId$
* ${other javadoc tags}
*/
</source>

For example the class <code>fr.utbm.set.gis.util.GISTreeSet</code>:

<source lang="java5">
/**
* This class describes a quad tree that contains GIS primitives
* and that permits to find them according to there geo-location.
*
* @param is the type of the user data inside the node.
* @author Stéphane GALLAND <stephane.galland@utbm.fr>
* @version $Name$ $Revision$ $Date$
* @mavengroupid $GroupId$
* @mavenartifactid $ArtifactId$
* @see GISPrimitive
*/
public class GISTreeSet implements Set {
</source>

= Eclipse Configuration =

Your Eclipse Platform should be configured as following: (section "Preferences> Java> Compiler> Javadoc") every options must be set to "Warning" and the visibility level should be set to "Private" or "Default".

To quickly configure your Eclipse, you may import the following preferences:
* Eclipse Galileo Preferences

= Related Pages =

* [[Developper_Conventions|Conventions and Guidelines for Developers]]

Coding Conventions

2010-09-02T19:21:35Z

Created page with '= General = Sun has established coding standards that are generally considered reasonable, as evidenced by their widespread adoption by other Java-based development efforts (e.g…'

New page

= General =

Sun has established coding standards that are generally considered reasonable, as evidenced by their widespread adoption by other Java-based development efforts (e.g., the Apache Jakarta project). One of the goals is to make the Janus projects blend in with the Java 2 platform. This goal is furthered by our following suit.

[http://java.sun.com/docs/codeconv/index.html Sun's Code Conventions for the Java Programming Language] covers filenames, file organization, indentation, comments, declarations, statements, white space, naming conventions, and programming practices. All code written for the Janus projects should follow these conventions except as noted below. We deviate only in places where our needs differ from Sun's; when we do deviate, we explain why. (The section numbers shown below are Sun's.)

= Additional Guidelines =

== Section 3.1.1 Beginning Comments ==

The Janus project has specific guidelines for copyright notices to appear at the beginning of source files. Each file must start with:

<source lang="java5">
/*
* $Id$
*
* Copyright (c) ${year}, ${developers}
* All rights reserved.
*
* http://www.janus-project.org
*/
</source>

== Section 5.2 Documentation Comments ==

The Janus project has specific guidelines for package, class and interface comments. Each package, class and interface must start the following comment template:

<source lang="java5">
/**
* ${comment about this feature}
*
* ${generic parameter comments}
* @author ${full name 2} <${email 1}>
* @author ${full name 2} <${email 2}>
* @version $Name$ $Revision$ $Date$
* @mavengroupid $GroupId$
* @mavenartifactid $ArtifactId$
* ${other javadoc tags}
*/
</source>

For example the class <code>fr.utbm.set.gis.util.GISTreeSet</code>:

<source lang="java5">
/**
* This class describes a quad tree that contains GIS primitives
* and that permits to find them according to there geo-location.
*
* @param is the type of the user data inside the node.
* @author Stéphane GALLAND <stephane.galland@utbm.fr>
* @version $Name$ $Revision$ $Date$
* @mavengroupid $GroupId$
* @mavenartifactid $ArtifactId$
* @see GISPrimitive
*/
public class GISTreeSet implements Set {
</source>

== Section 9 Naming Conventions ==

The Janus project has more specific naming conventions. See [[Naming_Conventions|Project Naming Conventions]] for details.

Additional Conventions about Property files
* Property files (<code>.properties</code> extension) are text files with Java resource descriptions. The following notice must appear at the beggining of each property file:

<source lang="bash">
# $Id$
#
# Copyright (c) ${year}, ${developers}
# All rights reserved.
#
# http://www.janus-project.org
</source>

= Eclipse Configuration =

Your Eclipse Platform should be configured as following: (section "Preferences> Java> Compiler> Error/Warnings"): every options must be set to "Warning", except for those in <xr id="tab:exceptions"/>.

<figtable id="tab:exceptions">
{| class=frametable
! Configuration Option
! Value
|-
| "Code Style> Parameter assignement"
| Ignore
|-
| "Potential programming problems> Boxing and unboxing conversions"
| Ignore
|-
| "Deprecated and restricted API> Deprecated API"
| Error
|-
| "Deprecated and restricted API> Forbidden reference"
| Error
|-
| "Unnecessary code> Parameter is never read"
| Ignore
|}
</figtable>

To quickly configure your Eclipse, you may import the following preferences:
* Eclipse Galileo Preferences

= Related Pages =

* [[Developper_Conventions|Conventions and Guidelines for Developers]]

Naming Conventions

2010-09-02T18:40:41Z

New page

= General =

The guidelines from this page are extracted from the [[eclipse:Development_Conventions_and_Guidelines|Eclipse Project Guidelines]].

== Workspace Projects ==

When Eclipse is being used to develop projects, the name of the Eclipse workspace project should match the name of the project. For example, <code>org.eclipse.core.runtime</code> plug-in is developed in an Eclipse workspace project named <code>org.eclipse.core.runtime</code>.

== Java Packages ==

Projects consist of a collection of Java packages. The package namespace is managed in conformance with Sun's package naming guidelines; subpackages should not be created without prior approval from the owner of the package subtree. The packages for the Janus projects are all subpackages <code>org.janusproject</code>.

The first package name segment after <code>org.janusroject</code> is generally the subproject name, followed by the component name.

== Additional Rules ==

Package names should contain only lowercase ASCII alphanumerics, and avoid underscore <code>_</code> or dollar sign <code>$</code> characters.

= Classes and Interfaces =

Sun's naming guidelines states:

<cite>Class names should be nouns, in mixed case with the first letter of each internal word capitalized. Try to keep your class names simple and descriptive. Use whole words - avoid acronyms and abbreviations (unless the abbreviation is much more widely used than the long form, such as URL or HTML).</cite>

Examples:
* <code>class Raster;</code>
* <code>class ImageSprite;</code>

Additional rules:
* Interface names should be capitalized like class names.
* Interface names should be adjectives or service name, and never be ended by the word <code>"Interface"</code>.
* The names of exception classes (subclasses of <code>Exception</code>) should follow the common practice of ending in <code>"Exception"</code>.

= Methods =

Sun's naming guidelines states:

<cite>Methods should be verbs, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized.</cite>

Examples:
* <code>run();</code>
* <code>runFast();</code>
* <code>getBackground();</code>

Additional rules:
* The names of methods should follow common practice for naming getters (<code>getX()</code>), setters (<code>setX()</code>), and predicates (<code>isX()</code>, <code>hasX()</code>).

= Variables =

Sun's naming guidelines states:

<cite>Except for variables, all instance, class, and class constants are in mixed case with a lowercase first letter. Internal words start with capital letters. Variable names should not start with underscore <code>_</code> or dollar sign <code>$</code> characters, even though both are allowed.
Variable names should be short yet meaningful. The choice of a variable name should be mnemonic - that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are <code>i</code>, <code>j</code>, <code>k</code>, <code>m</code>, and <code>n</code> for integers; <code>c</code>, <code>d</code>, and <code>e</code> for characters.</cite>

Examples:
* <code>int i;</code>
* <code>char c;</code>
* float myWidth;

= Constants =

Sun's naming guidelines states:

<cite>The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("<code>_</code>").</cite>

Examples:
* <code>static final int MIN_WIDTH = 4;</code>
* <code>static final int MAX_WIDTH = 999;</code>
* <code>static final int GET_THE_CPU = 1;</code>

= System Files and Settings =

By convention, files or folders that start with a period ('<code>.</code>') are considered "system files" and should not be edited by users or, directly, by other components that do not "own" them.

Of special note is the "<code>.settings</code>" folder in a workspace project. This folder holds various forms of preference or metadata specific to that workspace project. Files in this directory do not have to start with a period (they are assumed "system files" as they are in a "system folder") but they must follow the same naming conventions outlined elsewhere in this guide. That is, they must identify themselves with their project's namespace (e.g. <code>org.janusproject.kernel</code>, etc.). and they should be as specific as possible to denote the package they come from, or the function they are serving.

= Related Pages =

* [[Developper_Conventions|Conventions and Guidelines for Developers]]

FAQ

2010-09-02T18:25:11Z

← Older revision		Revision as of 18:25, 2 September 2010
Line 71:		Line 71:
	Janus Core Developers use a [https://devmas-set.utbm.fr/jira/ JIRA portal] to manage bug tracking and project workflow. To report your issue, you may fill the dedicated [[Bug Report]] forumular. Please read the [[Janus_Bug_Reporting_Style\|Janus Bug Report Guidelines]] before any submit.		Janus Core Developers use a [https://devmas-set.utbm.fr/jira/ JIRA portal] to manage bug tracking and project workflow. To report your issue, you may fill the dedicated [[Bug Report]] forumular. Please read the [[Janus_Bug_Reporting_Style\|Janus Bug Report Guidelines]] before any submit.

-	== What are the ~~version number policies applied on Janus projects~~? ==	+	== What are the conventions and the guidelines for developers? ==

-	~~Janus projects use the version number policies described on page~~ [[~~Version_and_Deprecation_Policies~~\|~~Version~~ and ~~Deprecation Policies~~]].	+	See [[Developper_Conventions\|Conventions and guidelines for developers]].

Developper Conventions

2010-09-02T18:22:53Z

Created page with 'As with any product being built by a team, there are various areas where standards, conventions, and other guidelines can play a role in helping to ensure that the resulting prod…'

New page

As with any product being built by a team, there are various areas where standards, conventions, and other guidelines can play a role in helping to ensure that the resulting product presents to developers and customers as a unified whole rather than as a loose collection of parts worked on by a variety of individuals each with their own styles and ways of working.

The following list of standards, conventions, and guidelines cover a wide range of aspects of the Janus projects:

* [[Version_and_Deprecation_Policies|Version Number and Deprecation Conventions]] How version numbers evolve and depecrated features are removed
* [[Naming Conventions]] How to name things like packages, classes, and methods
* [[Coding Conventions]] How to make Java code readable
* [[Javadoc Conventions]] How to write documentation comments, especially for API
* [[Graphic User Interface Conventions]] How to design a graphic user interface

FAQ

2010-09-02T08:11:59Z

← Older revision		Revision as of 08:11, 2 September 2010
Line 70:		Line 70:

	Janus Core Developers use a [https://devmas-set.utbm.fr/jira/ JIRA portal] to manage bug tracking and project workflow. To report your issue, you may fill the dedicated [[Bug Report]] forumular. Please read the [[Janus_Bug_Reporting_Style\|Janus Bug Report Guidelines]] before any submit.		Janus Core Developers use a [https://devmas-set.utbm.fr/jira/ JIRA portal] to manage bug tracking and project workflow. To report your issue, you may fill the dedicated [[Bug Report]] forumular. Please read the [[Janus_Bug_Reporting_Style\|Janus Bug Report Guidelines]] before any submit.
		+
		+	== What are the version number policies applied on Janus projects? ==
		+
		+	Janus projects use the version number policies described on page [[Version_and_Deprecation_Policies\|Version and Deprecation Policies]].

Version and Deprecation Policies

2010-09-02T08:09:46Z

Created page with 'In Janus projects, version numbers semantic is given by <xr id="tab:version"/> and associated constraints are explained on this page. <figtable id="tab:version"> {| class=framet…'

New page

In Janus projects, version numbers semantic is given by <xr id="tab:version"/> and associated constraints are explained on this page.

<figtable id="tab:version">
{| class=frametable
|+ <caption>Details of the Components of a Version Number</caption>
! Part
! Details
|-
| Major
| This value represents the version number for the application. The number will be increased each time there is a major change in functionality or a huge revision of the underlying architecture.
|-
| Minor
| This value is reset to 0 for every increase of the Major value. It will be increased when new functionality has been added, or when significant fixes have been made after problems have been reported.
|-
| Revision
| This value is reset to 0 for every increase of the Minor value. It will be increased when fixes have been applied after problems have been reported.
|}
</figtable>

=== Run Policies ===

* Major number 0 means beta version. The following constraints on major numbers are discarded.
* Let <math>x</math> and <math>y</math> two major numbers, so that <math>x \neq y</math>; source code running on <math>x</math> has no warranty to be runnable on <math>y</math>.
* Let <math>m</math> a major number, and <math>x</math>, and <math>y</math> two minor numbers so that <math>x < y</math>; all source codes running on <math>m.x</math> must be also runnable on version <math>m.y</math>.

=== Deprecation Policies ===

* When increasing major number, all the deprecated feature must be removed.
* Let <math>m</math> a major number, and <math>x</math>, and <math>y</math> two minor numbers so that <math>x < y</math>; in a feature is available on <math>m.x</math> and should disappear on <math>m.y</math>, it must be tagged as ''deprecated''.

Help:Editing

2010-08-30T12:49:07Z

← Older revision		Revision as of 12:49, 30 August 2010
Line 234:		Line 234:
	\|<code><jiraissuelist [search=""] [max=100000] [offset=0] [ascendent=true]> projectname1, projectname2, ... </jiraissuelist></code>		\|<code><jiraissuelist [search=""] [max=100000] [offset=0] [ascendent=true]> projectname1, projectname2, ... </jiraissuelist></code>
	\| See [[Issues:Janus]] or [[Issues:Jaak]].		\| See [[Issues:Janus]] or [[Issues:Jaak]].
		+	\|-
		+	! colspan=2 \| <h4 style="display:none;"><phone /></h4>Phone number formatting
		+	\|-
		+	\| <code><nowiki><phone>123456789</phone></nowiki></code>
		+	\| <phone>123456789</phone>
		+	\|-
		+	\| <code><nowiki><phone prefix="ar">123456789</phone></nowiki></code>
		+	\| <phone prefix="ar">123456789</phone>
	\|-		\|-
	! colspan=2 \| <h4 style="display:none;"><source /></h4>Source code formatting		! colspan=2 \| <h4 style="display:none;"><source /></h4>Source code formatting