Currently this is a hodgepodge placeholder for ideas and debate. This will be formatted and organized before 1.0 release.
This page is a guideline for those who want to develop Erlware itself. These standards are a good reference for Erlang development in general, but are a must for those developing on Erlware itself.
Since the 10th of April of 2008 we started to standardise our canonical repositories layout. You might find some non-compliant repositories yet, but in a reasonable time frame all will have, at least, next branches:
master: Current stable branch. It contains well tested stuff that is going to be in production. All releases are tags from this branch.
next: Public development HEAD. It contains stugg that will probably make
it into master within a reasonable short period, but that are not
necessarily well tested and might be broken or lack basic functionality
(e.g. due to a in-progress refactoring).
master is always a subset of next. Changes should only get to master as
merges or cheery-picks from next.
Usually, next branch is the best reference if you plan to build some patches
for a repository. In any case, it is advisable to contact its maintainer before
to avoid painful conflicting merges.
Terminal size: 132 is the erlware standard. Lines should not exceed this character max. For erlware-site, terminal size is 80 columns.
Trailing whitespace: You must not check in code with trailing whitespace
(space between last printable character and the end of the line). If you are
using emacs, you can use delete-trailing-witespace function to get rid of all
offending spaces in a buffer.
Indentation: We prefer the automatic indentation of erlware-mode.
Erlware requires a certain level of documentation for all code included in the central repository or as part of any Erlware project such as Sinan or Faxien. Basically the idea is that all API's should be documented to a level that a user could figure out how to use them without reading the code itself. Examples of invocation are very strongly recommended for all exported functions.
Erlware uses EDoc as its documentation standard. All code must compile with edoc. To check and see if your docs compile you can use the Sinan target doc.
Documentation for a module should appear at the top of the file. This is optional, but recommended.
All Exported functions should be documented. The following is an example that includes the minimum level of documentation an exported function should exhibit.
%%------------------------------------------------------------------------------
%% @doc I am a function and I do things.
%% @spec my_func(List, Atom::atom()) -> ok | {error, Reason}
%% @end
%%------------------------------------------------------------------------------
my_func(List, Atom) ->
...
Additional documentation may be added as allowed by Edoc. Any additional user formatted explanation for the function should be placed after @doc and before @spec such as in the following example.
%%------------------------------------------------------------------------------
%% @doc I am a function and I do such wonderful things.
%% <pre>
%% Example:
%% my_func([a, b], upgrade)
%% </pre>
%% @spec my_func(List, Atom::atom()) -> ok | {error, Reason}
%% where
%% List = [string()]
%% @end
%%------------------------------------------------------------------------------
my_func(List, Atom) ->
...
We do encourage developers to document internal functions but it is not required. If you do document internal functions the documentation should contain the @private tag as follows.
%%------------------------------------------------------------------------------
%% @private
%% @doc I am an internal function and I do things to support an API.
%% @spec my_internal_func(String::string()) -> ok | error
%% @end
%%------------------------------------------------------------------------------
my_internal_func(String) ->
...
For more information in improving the quality and style of your Erlang code consult the Erlang Erlang Programming Rules section hosted by erlang.org.