programming rules of thumb : Java Glossary
- programming rules of thumb
I have been programming professionally for 50 years. Here are some rules of thumb for computer programming that I
have learned from painful experience.
- When deciding on a set of categories, err on the side of making them too fine. It is easy to mechanically
coalesce the categories later for some new purpose, but very difficult to manually recode the data, splitting
them into finer categories.
- If you find yourself doing some repetitious, monotonous task, take the time to automate it, now.
This includes writing monotonous computer code. There are four benefits.
- You save the time doing it manually between now and the time the pain reaches the threshold that you
finally do automate it.
- You will do it consistently, accurately and properly from the get go. When you are automating, you tend
to think more carefully about precisely how something should be done.
- You won’t have an inconsistent mess to clean up when you finally do get around to automating
- Writing automating code is much more fun then tedious bullwork.
- Tell a computer any given fact in only one place. Lobby to fix up computer languages and tools so that when
you change a given fact in any one place, that change is automatically universally propagated. The Java
language flagrantly violates this principle with its casts. You specify the type of a variable over and over.
Ditto with new where you must respecify the type. You want to work toward a data
dictionary, where corporate variables, their names, definitions, bounds, error checks, display formats etc. are
all defined in one place, not implicitly buried in thousands of different bits of procedural code, SQL (Standard Query Language) and GUI (Graphic User Interface)
layouts. The Internet web also violates the principle. When a web page is retracted, renamed or moved, that
fact is currently not automatically propagated to all the links to it. You have a horrible entropy
problem and untold hours of wasted human effort maintaining web links.
- Be very careful to use consistent vocabulary. Create a glossary if you use any terms in particular
project-specific way. The terms may be obvious to you or your coworkers, since you use them consistently in
your informal conversations, but they usually highly ambiguous to someone coming in cold. The important thing
is rigid consistency. You are not writing a novel. You don’t want to imply subtle differences that are
not there. For example, consider the following list of verbs I have seen programmers use to mean
format to a string suitable for display to humans. Each has connotations that may or may
not have been intended.
Variants on the Verb Format
|Variants on the Verb Format|
||implies making visible|
||to a specific character set, implies a hard to read, external armoured (e.g. base64) or encrypyted
form, perhaps with some ugly convention for handling awkward characters.|
||like enclose or encapsulate|
||implies alternative layouts. This is what Sun uses. Does not imply any sort of I/O or display as a
||implies a bit map image|
||implies sending as a stream to disk|
||as in write to a printer or disk|
- When composing an essay, class or method, always err on the side of splitting it into pieces that are too
small. They will inevitable grow. It is much easier later to combine small pieces, if necessary, than split up
a big chunk.
- Literate naming is the #1 tool to writing maintainable code. Name classes, variables and methods in such a
way that in a blind alphabetical listing, related items will be close to each other in the list. Read my essay
on how to choose names for methods and variables. Read my tongue in cheek essay on
how to write unmaintainable code by malicious selection of arbitrary names. Use
the global rename feature of your IDE (Integrated Development Environment) exhaustively to continuously improve your names.
- Programming is a team sport. Even if you work alone as an independent contractor much of your success comes
from sweet talking people into giving you information and solving problems for you. Computer programmers tend
to have bigger than average egos which makes for trouble if you are not aware of the strong need for others to
save face. When you explain something, and the other person does not understand, don’t waste time
deciding whose fault it is. Simply accept that your explanation was not sufficient for them to get it. Both of
you wish it were. There is utterly no point in berating the other person for misinterpreting or failing to
understand your explanation. Think like a lawyer. How could someone intentionally twist the meaning of
your words? (not that they did). Then set about patiently removing the ambiguities. You can’t rely on
their common sense to resolve the ambiguities because common sense only kicks in once they have a general
understanding. I like to write essays on something very soon after I have learned it myself, even if that means
a few extra errors, that others delight in pointing out. That is when I am most expert on what is not