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
  Basis for the code conventions of the MyFaces project are Suns Java Code
  Conventions at
  http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
  Well as the initiators of this project we take the liberty to postulate one
  exception: Opening braces go on the next line and there is a new line after
  closing braces before else/catch/finally/while(in do-while)!  ;-)

* 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 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.

* 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

* CVS
  - 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 (myfaces-dev@incubator.apache.org).
  - Every active MyFaces developer must subscribe to this list.

* Copyright
  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$
 * $Log$
 * Revision 1.16  2004/10/29 15:50:59  mmarinschek
 * Get rid of many of the outdated references to sourceforge. set myfaces extensions tld uri to http://myfaces.apache.org/extensions
 *
 * Revision 1.15  2004/07/05 12:52:43  manolito
 * Apache License
 *
 * Revision 1.14  2004/04/20 18:07:16  bdudney
 * build file refactoring
 *
 * Revision 1.13  2004/03/25 09:14:52  manolito
 * no message
 */