OpenFlax Design Goal #3: Clarity

This rather broad goal includes simplicity, straightforwardness, readability, maintainability, generalization, and modularity.

This goal is sometimes seen as subjective, with each programmer preferring his or her own programming style. That is why I chose the word clarity to convey a quality that is not purely subjective: a program is clear if it is easy for the average programmer to comprehend what it does.

A large part of this depends on the quality of the documentation, both the documents external to the program, and the comments inside it.

While it is difficult to measure the quality of documentation, it is possible to measure the quantity of the documentation, especially the frequency of comments.

The following table is a brief analysis of the comment:code ratio of OpenFlax and the leading Erlang web servers:

application	version	lines	code lines	blank lines	comment lines	comment:code
yaws	1.30	8587	6542	1417	628	0.10
inets	3.0.6	6236	4191	1005	1040	0.25
openflax	2003.0927	2235	1087	282	866	0.80
pico	JUNGERL	608	444	96	68	0.15

Unfortunately, this only considers lines which contain nothing but a comment. As this does not include seperate documentation nor lines which include comments as well as code, and as it includes license information, commented-out sections of code, and other largely-irrelevant 'comments', and as the simple source checker may be confused by a comment symbol in a string literal, it is not entirely representative.

In light of these results, the following maxims apply to the programming style employed in OpenFlax:

Endeavour to adhere to the Erlang Programming Rules and Conventions as they apply to writing maintainable code.
Give as descriptive and verbose names as reasonably possible to all identifiers (functions, modules, variables, settings, etc.)
Auto-document the source code to expose its interfaces.
Write code in a very straightforward style, bordering on the pedantic. Avoid macros and performance "tricks" like the plague.
Package functionality sanely.
Use the same, consistent format for all configuration information. For example, don't have a seperate file listing MIME type associations; integrate these with the rest of the configuration.