programming rules of thumb : Java Glossary
©1996-2017 2008-08-08 Roedy Green of Canadian Mind Products
- programming rules of thumb
I have been programming professionally for 54 years.
Here are some rules of thumb for computer programming that I have learned from
- 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
- 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 it.
- 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
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 side effect.|
||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