src/development/standards.page

   1 ---
   2 title: Standards
   3 directory: Development
   4 inMenu: true
   5 orderInfo: 2
   6 ---
   7
   8 # Erlware Development Standards
   9
  10 Currently this is a hodgepodge placeholder for ideas and debate.  This
  11 will be formatted and organized before 1.0 release.
  12
  13 This page is a guideline for those who want to develop Erlware itself.
  14 These standards are a good reference for Erlang development in
  15 general, but are a must for those developing on Erlware itself.
  16
  17 # Repository Standards
  18
  19 Since the 10th of April of 2008 we started to standardise our canonical
  20 repositories layout. You might find some non-compliant repositories yet, but
  21 in a reasonable time frame all will have, at least, next branches:
  22
  23  * **master:** Current stable branch. It contains well tested stuff that is
  24    going to be in production. All releases are tags from this branch.
  25
  26  * **next:** Public development HEAD. It contains stugg that will probably make
  27    it into `master` within a reasonable short period, but that are not
  28    necessarily well tested and might be broken or lack basic functionality
  29    (e.g. due to a in-progress refactoring).
  30
  31 `master` is always a subset of `next.` Changes should only get to master as
  32 merges or cheery-picks from `next.`
  33
  34 Usually, `next` branch is the best reference if you plan to build some patches
  35 for a repository. In any case, it is advisable to contact its maintainer before
  36 to avoid painful conflicting merges.
  37
  38 # Coding Standards
  39
  40 **Terminal size:** 132 is the erlware standard.  Lines should not
  41   exceed this character max. For erlware-site, terminal size is 80 columns.
  42
  43 **Trailing whitespace:** You must not check in code with trailing whitespace
  44 (space between last printable character and the end of the line). If you are
  45 using emacs, you can use `delete-trailing-witespace` function to get rid of all
  46 offending spaces in a buffer.
  47
  48 **Indentation:** We prefer the automatic indentation of
  49 [erlware-mode]({relocatable:../tools/erlware-mode}).
  50
  51 # Documentation Standards
  52
  53 Erlware requires a certain level of documentation for all code
  54 included in the central repository or as part of any Erlware project
  55 such as Sinan or Faxien.  Basically the idea is that all API's should
  56 be documented to a level that a user could figure out how to use them
  57 without reading the code itself.  Examples of invocation are very
  58 strongly recommended for all exported functions.
  59
  60 Erlware uses EDoc as its documentation standard.  All code must
  61 compile with edoc.  To check and see if your docs compile you can use
  62 the Sinan target **doc.**
  63
  64 ## Module Documentation
  65
  66 Documentation for a module should appear at the top of the file.  This
  67 is optional, but recommended.
  68
  69 ## Function Documentation
  70
  71 All Exported functions should be documented. The following is an
  72 example that includes the minimum level of documentation an exported
  73 function should exhibit.
  74
  75
  76     %%------------------------------------------------------------------------------
  77     %% @doc I am a function and I do things.
  78     %% @spec my_func(List, Atom::atom()) -> ok | {error, Reason}
  79     %% @end
  80     %%------------------------------------------------------------------------------
  81     my_func(List, Atom) ->
  82     ...
  83
  84 Additional documentation may be added as allowed by Edoc.  Any
  85 additional user formatted explanation for the function should be
  86 placed after @doc and before @spec such as in the following example.
  87
  88
  89     %%------------------------------------------------------------------------------
  90     %% @doc I am a function and I do such wonderful things.
  91     %% <pre>
  92     %% Example:
  93     %%  my_func([a, b], upgrade)
  94     %% </pre>
  95     %% @spec my_func(List, Atom::atom()) -> ok | {error, Reason}
  96     %% where
  97     %%       List = [string()]
  98     %% @end
  99     %%------------------------------------------------------------------------------
 100     my_func(List, Atom) ->
 101     ...
 102
 103
 104 We do encourage developers to document internal functions but it is
 105 not required.  If you do document internal functions the documentation
 106 should contain the @private tag as follows.
 107
 108
 109     %%------------------------------------------------------------------------------
 110     %% @private
 111     %% @doc I am an internal function and I do things to support an API.
 112     %% @spec my_internal_func(String::string()) -> ok | error
 113     %% @end
 114     %%------------------------------------------------------------------------------
 115     my_internal_func(String) ->
 116     ...
 117
 118
 119 # Additional Resources
 120
 121 For more information in improving the quality and style of your Erlang
 122 code consult the Erlang [Erlang Programming
 123 Rules](http://www.erlang.se/doc/programming_rules.shtml) section
 124 hosted by erlang.org.
 125