programming rules of thumb : Java Glossary

2008-08-08 by Roedy Green ©1996-2009 Canadian Mind Products
index page for letter ⇒ punctuation 0-9 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z (all)

programming rules of thumb

I have been programming professionally for 46 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 in to 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.
1. You save the time doing it manually between now and the time the pain reaches the threshold that you finally do automate it.
2. 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.
3. You won’t have an inconsistent mess to clean up when you finally do get around to automating it.
4. 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 and GUI 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
Term	Notes
asString
denote
designate
display	implies making visible
encode	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.
enstring	like enclose or encapsulate
evaluate
exhibit
express
flatten
format	implies alternative layouts. This is what Sun uses. Does not imply any sort of I/O or display as a side effect.
getAsString
getString
present
print	implies hardcopy
render	implies a bit map image
represent
serialize
stringize
stream	implies sending as a stream to disk
stringify
toString
write	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 an 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 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 obvious.

coding conventions
naming methods and variables

	Please email your feedback for publication, errors, omissions, broken/redirected link reports and suggestions to improve this page to Roedy Green :
	Canadian Mind Products
	mindprod.com IP:[65.110.21.43]
	Your face IP:[38.103.63.58]
	You are visitor number 11.
	You can get a fresh copy of this page from:	or possibly from your local J: drive (Java virtual drive/mindprod.com website mirror)
	http://mindprod.com/jgloss/programmingrules.html	J:\mindprod\jgloss\programmingrules.html