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

[steve ryan]

consistent descriptive variable names to allow intraspection
+1
good scheme

Happy to recommend a free typing tutor to those in need. ;-

Natural language is an interesting concept I haven't met. Might be some 
interesting interpretations of 'natural' word ordering in an 
international community forced to speak English. Mind you, most of the 
Germans I've met speak better English than me.

Stever


Elmar Hinz wrote:
> 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.