MyFaces Developer Notes
=======================

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

(also see FAQs.txt)

======================================================================
Component developer guidelines

* Properties and attributes
  MyFaces' MinimizingStateSaver is only able to save the state of a component,
  if all important (state relevant) values are stored as bean properties. So,
  every member field that should be saved between requests, must have a public
  getter and also a public setter method.
  Also have in mind, that StateSaver does not save renderer dependent attributes
  that have names starting with "net.sourceforge.myfaces.", "net.sf.myfaces."
  or "javax.". These are regarded temporary attributes and will not be saved and
  restored!

* Component property getters must not behave dynamically. Avoid doing something
  that depends on the current FacesContext.
  Reason: Minimizing State Saver only saves a property if it's value differs
  from the corresponding component in the parsed static tree. Now, if the getter
  method calculates the value dynamically, both components (the current and the
  static one in the parsed tree) will have the same value and the property will
  not be saved.

* To achieve universal usability default HTML renderers must not render any
  client-side scripting (JavaScript) and must not depend on stylesheets.
  - There are plans to start a parallel package "html_javascript" in the future
    where such renderers will reside. But keep in mind that these renderers
    must always be seen as alternative (extended) renderers.
  - Default renderers may use style attributes to embellish visible components.
    Despite this, the functionality of a component must never be affected when
    displayed without style (e.g. user mode in Opera).

======================================================================
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)!  ;-)

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

* Communication
  - Main communication instrument among MyFaces developers is the MyFaces
    developer mailing list (myfaces-develop@lists.sourceforge.net).
  - Every active MyFaces developer must subscribe to this list.

* Copyright
  Every file should start with the following copyright notice:
/**
 * MyFaces - the free JSF implementation
 * Copyright (C) 2003  The MyFaces Team (http://myfaces.sourceforge.net)
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library 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
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 */

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