[TYPO3-ect] Draft: Naming Guidelines of tx_div and tx_lib

[Elmar Hinz]

Naming Guidelines of tx_div and tx_lib

Computer programms need to be readable by humans and machines. If we
would like to write programms that are best readable for the machine,
we could programm in machine code. But we don't do this because human
readabilty of the code is important for us. Best readabilty for humans
is a matter that we need to spend some thoughts to. Espacially for
opensource code, that is written to be easy understandable for a lot
of people. Good code should document itself.

To make extension development easy and intuitive, we aim to use a
natural grammer and common terms of full length whereever possible
throughout this libraries. We follow this rules for the names of
classes, functions and class variables.

Inside a function variales may be abbreviated because the namespace of
function is so limited that misunderstandings can be most likly avoided.

We also encourage the users of the library to follow these principles.


Natural Grammer

How many misunderstands produces a term like "atagbefore"? A tag
before what? An A-tag? Before the A-tag? The A-tag before? What do you
better understand and remember "get left content" or "content get left"?

In this library we build names in a way that follows the grammer of
human language.  We say $firstNameOfUser or $usersFirstName but never
$namesUserFirst.


Using Plural for Plurals

When there are more then one units in something we use the plural of
the unit or the singular of the matching container. An array with names:

right: $userNames  :    $userNames[]  = 'Martin';
right: $userList: 	$userList[]   = 'Martin';      // container

wrong: $userName:       $userName[]   = 'Maritn';
wrong: $usersNames:     $usersNames[] = 'Maritn';
wrong: $userLists: 	$userLists[]  = 'Martin';      // container

A database table with names is called tx_names not tx_name

A directory with controllers is called controllers/ not controller/



Using CamelCase to reserve Underscores

To compose words we use CamalCase. That is not a matter of taste but
has good reasons. Underscores and hyphens need to be reserved for
special tasks.

Example: autoloading of classes

If we want to use the name of a class to locate the class
automatically in the directory, we set the underscores where a
directory slash will be placed in. So we automatically can load classes:

tx_myextension_controllers_book  from

typo3conf/ext/myextension/controllers/book

If you select names please keep in mind, that some operating systems
don't know the difference of uppercase and lowercase for pathes.

On windows this is the same path:

tx/myextension/babel and tx/myextension/baBel

So you should only use one of the classnames:

tx_myextension_babel or  tx_myextension_baBel



Avoiding Abbreviations

There are a lot of programmers that use their own style of cryptic
abbreviations for all and everything. The reader of such code may be
impressed but doesn't understand a single line. The programmer spends
a lot of time hereafter to document his code and explain what all this
abbreviations mean. If he does at all.

If a second programmer works on with this code he has his own style of
abbreviations and what surely will be a regular source not only of
compile time errors. What is ctime? Time of change? Time of creation?
What is uid? User identification? Unique ID? How would you abbreviate
password? PW, pwd, pass, passwd? How do you abbreviate character? chr?
char?

In this library we use the full words instead of abbreviations, to be
human readable and to have clear method names. There will allways be a
function name in full length of words:

unsetUserPassword();
setCharacter($character);

For the convinience of the users there may by additional abbreviated
forms of a full name function. uup() may be available as alternative
to unsetUserPassword(). But there will never be an abbreviated form
without the full name version also available. The abbreviated form
will not be used inside the libraries tx_lib and tx_div, for reasons
of self explaining sourcecode.