[Rbopensource-developer] Naming Conventions for Realbasic: RFC 1

[Fabian R. <fa...@ru...>]

Hi everyone,

I've finally found the time to write up a general recommendation on 
how to name variables, objects, etc. in Realbasic. It is based on the 
previous mail exchange on this list with a focus on readability of 
code.

I've called this an RFC (request for comment) because that's what it 
is. Please feel free to send your change proposals via this list, so 
we can talk them through and (by majority decision or whatever's 
necessary) agree on a general naming _recommendation_ for RB open 
source code. Arguably one might want to have stricter conventions, 
but I set them up pretty liberal, I guess.

Please tell me what you think,

Yours

=46abian

PS. I've attached it as an extra text file, and pasted it also in 
below for your convenience:
----------------------------------------------------------------
--------------------------------------------------------------------------
NAMING RECOMMENDATIONS FOR REALBASIC:
1st Draft (RB-OPENSOURCE RFC 1):
=A9Fabian Rueger for RB OpenSource Project at sourceforge.net,
November 1, 2002.

TABLE OF CONTENTS:

1. Purpose of this document
2. Global vs OOP naming
3. General naming conventions
	3.1 Requirements of Code readability
	3.2. Lower and uppercase in names
4.  Naming conventions
	4.1 Globals
	4.2 Local Variables
	4.3 Class and Instance Names
	4.4 Object property, method and function names
	4.5 Specific class and OOP names
	4.6 Constants
		4.6.1 Local and object constants
		4.6.2 Global constants

-----------------------------------------
1. Purpose of this document:
This document contains recommendations for naming variables, codes,
methods and constants in an RB project. For the purpose of this
document, all methods, function and variable declarations are considered
'names', and RB programmers are called 'authors'.

It is intended not to be a strict set of rules but a recommendation for
Open Source authors to enable Open Source projects to interact with each
other smoothly by avoiding namespace conflicts of these code
declarations. Authors are asked to accept these guidelines for 
writing reusable code.

Within this text, SHOULD resembles a recommendation for naming,
COULD/MIGHT an option, while MUST and MUST NOT represent strict
requirements for the rest of the guidelines to make sense. This document
is not authorized in any way by RealSoftware Inc.

-----------------------------------------
2. Global vs OOP naming

Since in any case the best approach for all open source projects is to
be as object oriented as possible, any open source code meant to be
easily exchangeable between projects should if at all possible avoid
requiring global methods, functions or constants. If the code requires
globals, their names should be marked by an additional prefix to all
other naming conventions. This prefix should be a lowercase g (for
'global').

-----------------------------------------
3. General naming conventions

-----------------------
3.1 Requirements of Code readability
To guarantee the best readability of code, authors should name all code
vars and calls best in full wording. RB's autocomplete feature takes
away most of the typing work for us, therefore name length is not really
an issue. Since BASIC was a language with human readability in mind
authors should consider this as strength of the language. Authors MUST
NOT abbreviate names and SHOULD choose names best describing the
specific function of the code piece to the fullest. Authors SHOULD avoid
simplistic names with multiple meanings as name declarations for the
sake of more detail (e.g. "AddTwoIntegers" rather than "Add" for a
function that adds two integers).

-----------------------
3.2. Lower and uppercase in names
Lower and uppercase letters are used to distinguish between words within
a name; it is only at the beginning of a name that lower or uppercase
letter prefixes should resemble a distinction signal between aspects of
code. For readability, longer names containing several words should
begin each new word with a capital letter with the exception of the
first. The only exception are global constants (c.f 4.6.2). Authors MUST
NOT name any properties, methods or names with all-capital letters
except global constants.

-----------------------------------------
4.  Naming conventions

-----------------------
4.1 Globals
All globals should have the prefix 'g' with the exception of global
constants (cf. 4.6.2).

-----------------------
4.2 Local Variables
In methods and functions, local variables should be rather short than
descriptive, to avoid name conflicts. Authors COULD name each function's
result as 'result' to have unified return naming conventions. If this is
used throughout code, readability is much improved.
Authors SHOULD in general use lowercase-only names in local variables.
Short names (e.g. x,y,cnt,f) MUST be entirely reserved for local variables.

-----------------------
4.3 Class and Instance Names

Each class SHOULD simply end with the term "Object" to signal that it is
the class, rather than an instance of it. This allows to have instances
of a class that bear the name of the class, without having a name
conflict.
Objects/instances MUST have a name that is descriptive of their
content/use. Authors SHOULD give instances of classes names that begin
with a capital letter, to distinguish them from RB's regular variables.
Parent/child relationships between classes SHOULD be suggested by at
least keeping a part of the super class name in the last part of the
child class name. (see 4.5). The word 'Object' as the last part of a name
MUST be reserved for classes.

	Example: Assuming you have a class that contains a list of names, you
	could call it "NameListObject". This allows for code such as:
	Dim FirstNameList as NameListObject
	FirstNameList=3Dnew NameListObject

-----------------------
4.4 Object property, method and function names
The above rules apply similarly to methods, functions and properties 
of a class. Method or function parameters SHOULD especially have 
descriptive intuitive names. Since RB's tip window displays the name 
of parameter variables of a function or method, a descriptive name 
here especially helps to speed up coding.

All regular datatypes of RB MUST, as properties or variables, always 
begin with lowercase letters.

Method names SHOULD contain a verb to clearly distinguish them from 
functions (to signal they alter data, rather than merely reading out 
data), whereas functions SHOULD be preceded or signaled by similarly 
appropriate wording like "Get", "Find", etc.
Note that both functions and methods SHOULD begin with initial 
capital letters to clearly distinguish them from regular object 
properties.

	Example: A function that returns the square root of an object's
	properties might be called "GetSquareRoot" instead of just
	"SquareRoot" to suggest it merely returns a value. Similarly, a method
	that would set an object's internal properties to such square root
	should then be called "SetSquareRoot" or "MakeSquareRoot".

	Example 2:
	"MoveLeft(horizontalPixels, verticalPixels, speed)" is more descriptive
	than "MoveLeft(x,y,s)"

-----------------------
4.5 Specific class and OOP names
Specific inherent RB subclasses SHOULD be named along the rule that 
they end with the RB parent class, followed by 'Object' for a class, 
and nothing but for the instance.

	Examples: -Window subclasses SHOULD always end with "WindowObject".
	-Appropriately, window instances SHOULD always end with "Window".
	-The same would then apply to all objects, e.g.,
	"MySMTPSocket","SMTPSocketObject".

Authors COULD additionally name all interface classes with a preceding 'i'.

-----------------------
4.6 Constants
Generally, constants should be signaled by a preceding 'k'. This has 
become convention among most RB programmers.

--------------
4.6.1 Local and object constants
=2E..should begin with a 'k', and be followed by a capital letter for 
readability.
	Example: kMaxFiles.

--------------
4.6.2 Global constants
Authors could either follow the above conventions (4.1 & 4.6) and 
precede all global constants with a 'gk'; for readability they MIGHT 
choose to instead use all-capital letters.

	Example: Instead of using gkPi=3D3.14159 authors MIGHT choose to use
	PI=3D3.14159 in a global context.

--------------------------------------------------------------------------