Differences between revisions 1 and 2
Revision 1 as of 2005-07-21 16:42:46
Size: 3766
Editor: 80-58-33-46
Comment: Copied from the old repo
Revision 2 as of 2005-07-21 16:52:24
Size: 3774
Editor: 80-58-33-46
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
This document deals with issues that are important for MyFaces developers This document deals with issues that are important for !MyFaces developers
Line 17: Line 17:
 * If there is no change to get the system back to a stable state, a message with severity "fatal" should be logged and a RuntimeException (or derived class) should be thrown. Vice versa: Whenever a RuntimeException (or derived class) is thrown, a message with severity "fatal" must have been logged right before.  * If there is no change to get the system back to a stable state, a message with severity "fatal" should be logged and a !RuntimeException (or derived class) should be thrown. Vice versa: Whenever a !RuntimeException (or derived class) is thrown, a message with severity "fatal" must have been logged right before.
Line 24: Line 24:
Naming is a fundamental concern. The name of a class, method or field should tell as much as possible of it's meaning and usage. Avoid short names like "Helper", "calc" or "check". Use "FinancialConsultance", "calculateMyYearlyIncome" and "isMyIncomeTooLow" instead. Naming is a fundamental concern. The name of a class, method or field should tell as much as possible of it's meaning and usage. Avoid short names like "Helper", "calc" or "check". Use "!FinancialConsultance", "calculateMyYearlyIncome" and "isMyIncomeTooLow" instead.
Line 28: Line 28:
Addition special comments (see 10.5.4 in CodeConv) Addition special comments (see 10.5.4 in !CodeConv)
Line 42: Line 42:
 * Main communication instrument among MyFaces developers is the MyFaces developer mailing list (dev@myfaces.apache.org).
 * Every active MyFaces developer must subscribe to this list.
 * Main communication instrument among !MyFaces developers is the !MyFaces developer mailing list (dev@myfaces.apache.org).
 * Every active !MyFaces developer must subscribe to this list.

MyFaces Developer Notes

This document deals with issues that are important for MyFaces developers and custom component developers.

Component developer guidelines

(same as "MyFaces developers guidelines", see below)

MyFaces developers guidelines

Code style

See http://www.apache.org/dev/styleguide.html for the Apache-Wide Coding Style Guide. Everything that is not documented there should be written according to Suns Java Code Conventions at http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html

Error and exception handling

Whenever an exception is caught, the following applies:

  • If there is no change to get the system back to a stable state, a message with severity "fatal" should be logged and a RuntimeException (or derived class) should be thrown. Vice versa: Whenever a RuntimeException (or derived class) is thrown, a message with severity "fatal" must have been logged right before.

  • If the exception is severe, but there is a chance to continue processing, a message with severity "error" or "warning" should be logged.

Logging

Except in the JSF API (javax.faces.*) classes, where there must not be any dependencies to additional libraries, commons-logging is used for logging generally. Commons-logging should be used in the recommended way, i.e. each class has it's own private static logger.

Naming

Naming is a fundamental concern. The name of a class, method or field should tell as much as possible of it's meaning and usage. Avoid short names like "Helper", "calc" or "check". Use "FinancialConsultance", "calculateMyYearlyIncome" and "isMyIncomeTooLow" instead.

Special comments

Addition special comments (see 10.5.4 in CodeConv)

  • TODO: something that is not yet ready

  • HACK: something that is bogus but (meanwhile) necessary to make it work

  • XXX: something that is bogus but works

  • FIXME: something that is bogus and broken

Version Control
  • Every developer may upload files, if (s)he is confident, that this file is usable for others.
  • Uploaded java files must be compilable, of course.
  • Changes to java files must leave the whole project in a state where it is still compilable.
  • Foreign files should only be committed (changed) after consulting and/or informing the original author. The same applies for deleting, of course. Exception: Trivial changes such as spelling mistakes in comments, etc.
  • Just to be sure: Don't forget the message(s) on commit ;-)

Communication
  • Main communication instrument among MyFaces developers is the MyFaces developer mailing list (dev@myfaces.apache.org).

  • Every active MyFaces developer must subscribe to this list.

Every file should start with the following copyright notice:

/**
 * Copyright 2004 The Apache Software Foundation.
 *
 * Licensed 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.
 */

* Class and Interface comment
  Every class and interface should have a javadoc similar to this:
/**
 * Very detailed description goes here... ;-)
 *
 * @author Bug Rogers (latest modification by $Author$)
 * @version $Revision$ $Date$
 */

MyFaces_Developer_Notes (last edited 2011-08-23 21:36:55 by LeonardoUribe)