Names

Make Names Fit

Names are the heart of programming. In the past people
believed knowing someone's true name gave them magical power over that person.
If you can think up the true name for something, you give yourself and the
people coming after power over the code. Don't laugh!

A name is the result of a long deep thought process about the ecology it
lives in. Only a programmer who understands the system as a whole can create a
name that "fits" with the system. If the name is appropriate everything fits
together naturally, relationships are clear, meaning is derivable, and reasoning
from common human expectations works as expected.

If you find all your names could be Thing and DoIt then you should probably
revisit your design.

Class Names

Name the class after what it is. If you can't think of what it is that is
a clue you have not thought through the design well enough.

Compound names of over three words are a clue your design may be confusing
various entities in your system. Revisit your design. Try a CRC card session
to see if your objects have more responsibilities than they should.

Avoid the temptation of bringing the name of the class a class derives
from into the derived class's name. A class should stand on its own. It
doesn't matter what it derives from.

Method and Function Names

Usually every method and function performs an action, so the name should
make clear what it does: CheckForErrors() instead of ErrorCheck(),
DumpDataToFile() instead of DataFile(). This will also make functions and data
objects more distinguishable.

Suffixes are sometimes useful:

Max - to mean the maximum value something can have.

Cnt - the current count of a running count variable.

Key - key value.

For example: RetryMax to mean the maximum number of retries, RetryCnt to
mean the current retry count.

Prefixes are sometimes useful:

Is - to ask a question about something. Whenever someone sees
Is they will know it's a question.

Get - get a value.

Set - set a value.

For example: IsHitRetryLimit.

No All Upper Case Abbreviations

When confronted with a situation where you could use an all upper case
abbreviation instead use an initial upper case letter followed by all lower
case letters. No matter what.

Do use: GetHtmlStatistic. Do not use:
GetHTMLStatistic.

Justification

People seem to have very different intuitions when making names containing
abbreviations. It's best to settle on one strategy so the names are absolutely
predictable.

Take for example NetworkABCKey. Notice how the C from ABC and K from
key are confused. Some people don't mind this and others just hate it so
you'll find different policies in different code so you never know what to
call something.

Layout

If you have else if statements then it is usually a good idea to
always have an else block for finding unhandled cases. Maybe put a log message
in the else even if there is no corrective action taken.

Condition Format

Always put the constant on the left hand side of an
equality/inequality comparison. For example:

if ( 6 == $errorNum ) ...

One reason is that if you leave out one of the = signs, the pharser will find
the error for you. A second reason is that it puts the value you are looking for
right up front where you can find it instead of buried at the end of your
expression. It takes a little time to get used to this format, but then it
really gets useful.

switch Formatting

Falling through a case statement into the next case statement shall be
permitted as long as a comment is included.

The default case should always be present and trigger an error if
it should not be reached, yet is reached.

Example

One Statement Per Line

There should be only one statement per line
unless the statements are very closely related.

Short Methods

Methods should limit themselves to a single page of code.

Justification

The idea is that the each method represents a technique for achieving a
single objective.

Most arguments of inefficiency turn out to be false in the long run.

True function calls are slower than not, but there needs to a thought out
decision (see premature optimization).

Document Null Statements

Always document a null body for a for or while
statement so that it is clear that the null body is intentional and not missing
code.

while ($dest++ = $src++)
; // VOID

Do Not Default If Test to Non-Zero

Do not default the test for
non-zero, i.e.

if (FAIL != f())

is better than

if (f())

even though FAIL may have the value 0 which PHP considers to be
false. An explicit test will help you out later when somebody decides that a
failure return should be -1 instead of 0. Explicit comparison should be used
even if the comparison value will never change; e.g., if (!($bufsize %
strlen($str))) should be written instead as if (0 == ($bufsize %
strlen($str))) to reflect the numeric (not boolean) nature of the test. A
frequent trouble spot is using strcmp to test for string equality, where the
result should neverever be defaulted.

The non-zero test is often defaulted for predicates and other functions or
expressions which meet the following restrictions:

Returns 0 for false, nothing else.

Is named so that the meaning of (say) a true return is absolutely
obvious. Call a predicate IsValid(), not CheckValid().

The Bull of Boolean Types

Do not check a boolean value for equality with 1 (TRUE, YES, etc.); instead
test for inequality with 0 (FALSE, NO, etc.). Most functions are guaranteed to
return 0 if false, but only non-zero if true. Thus,

if (TRUE == func()) { ...

must be written

if (FALSE != func()) { ...

Usually Avoid Embedded Assignments

There is a time and a place for
embedded assignment statements. In some constructs there is no better way to
accomplish the results without making the code bulkier and less readable.

while ($a != ($c = getchar())) {
process the character
}

The ++ and -- operators count as assignment statements. So, for many
purposes, do functions with side effects. Using embedded assignment statements
to improve run-time performance is also possible. However, one should consider
the tradeoff between increased speed and decreased maintainability that results
when embedded assignments are used in artificial places. For example,

$a = $b + $c;
$d = $a + $r;

should not be replaced by

$d = ($a = $b + $c) + $r;

even though the latter may save one cycle. In the long run the time
difference between the two will decrease as the optimizer gains maturity, while
the difference in ease of maintenance will increase as the human memory of
what's going on in the latter piece of code begins to fade.

HTTP_*_VARS

HTTP_*_VARS are either enabled or disabled. When enabled
all variables must be accessed through $HTTP_*_VARS[key]. When disabled all
variables can be accessed by the key name.

Enable .html and .php files to be pharsed by PHP in your webserver
configuration.

When you choose to use the .html extension on all your
web documents, you should put all your libraries in files with the extension
.php. When compared with the c language, the .c becomes .html and .h becomes
.php.

Justification

The extension describes what data the user will recive. Pharsed PHP
becomes HTML. (Example: If you made a software who encoded mp3 files, you
wouldn't use the extension .mysoft for the encoded files)

The use of .inc or .class can be a security problem. On most servers these
extensions aren't set to be run by a pharser. If these are accessed they will
be displayed in clear text.

Use if (0) to Comment Out Code Blocks

Sometimes large blocks of code
need to be commented out for testing. The easiest way to do this is with an if
(0) block:

Attributes as Objects is clean from a name perspective. When possible use
this approach to attribute access.

PHP Code Tags

PHP Tags are used for delimit PHP from html in a file.
There are serval ways to do this. <?php ?>, <? ?>, <script
language="php"> </script>, <% %>, and <?=$name?>. Some of
these may be turned off in your PHP settings.

In the above example what do 22 and 19 mean? If there was a number change
or the numbers were just plain wrong how would you know?

Heavy use of magic numbers marks a programmer as an amateur more than
anything else. Such a programmer has never worked in a team environment or has
had to maintain code or they would never do such a thing.

Instead of magic numbers use a real name that means something. You should use
define(). For example: