Developer Notes
Any kind of contribution is welcomed. To find out what contributions
we need most, please check Help Needed section in package.html
of every package. To maintain consistency, please follow our
guidelines described here.
I use XEmacs 21.2 in Linux 2.2
i386 with IBM JDK 1.3
and
Jikes
as my development environment. Someone claims true hackers spend 60%
of their (computer) time within emacs - and you better believe it!
It's a steep learning curve to learn emacs, but it's worth every
tick of the time.
A journey of a thousand miles begin with a
single step.
-- Confucius
Style
- use gtk naming (instead of standard sun java convention), extra
spacing between punctuation
- avoid prefix and suffix in name, use package and inner class:
gnu.x11.GC.Values
vs. gnu.x11.GCValues
gnu.x11.event.ButtonPress
vs.
gnu.x11.event.ButtonPressEvent
- use SPACE instead of TAB; use two spaces for indentation
- make variables and methods
public
instead of
private
to maximize utility
- sort variables and methods in class by lexicographical order of
names (ignore modifiers and types)
- place variables first, constructors second, inner classes third, methods last
- group methods of significant numerical order (such as protocol
number or mask value)
- group constants and inner classes just before their relating
methods
- group one-line methods after constructors
- use
{@link foo}
or
<code>foo</code>
in javadoc comments
; use `foo'
in internal comments
- use possible and valid to specific possible/valid
parameters or return values
- use full-signature
GC.Values#set_background(int)
instead of GC.Values#set_background
to avoid lossage when
overloading methods later
- use string array (
Connection.SEND_MODE_STRINGS
) to
index printable strings of enumeration constants
- lower letter and use dash
"-"
in place of underscore
"_"
when convert a variable (ROUND_TRIP
in
Connection
) to its printable string
(round-trip
)
- prefix setter methods with
"set_"
; avoid
prefix getter methods with "get_"
, also avoid
"choose_"
, "fetch_"
, "find_"
,
and "query_"
.
- use keywords:
- build for named constructors
- handle for handling events
- intern for interning resource ids
- create for creating resources
- Reply for replies from server
- use explicit import statement instead of
import foo.*
,
unless there are more than ten names from the same package
- use its fully-qualified object name instead of importing when
there are fewer than two statements using that name
- for summary sentence in java comment:
- start with either a verb or a noun
- use singular form of verb ("Provide X protocols" vs. "Provides X
protocols")
- for white-line spacing:
- no white-line before
package
- one white-line between
package
and
import
- two white-lines between
import
and class
- two white-lines before and after multi-line methods or fields
- no white-lines between one-line methods or fields
- start a general message with a capital letter and ends it with a period
- start an error message with a capital letter and ends it without
a period
The following techniques and conventions may seem inefficient, but I
assume (REQUIRE!!) an advanced compiler (or jit) will do appropriate
optimizations to make these styles neat as well as optimized:
- inline functions - instead of putting chucks of codes in
one big method, subdivide them into smaller methods to improve code
readability; maximize code abstraction by putting common codes into
separate methods and using extra levels of method calls --> javac,
please inline small methods and judge space vs. speed for me
- temporary objects - allocate temporary objects inside
methods instead of allocating as class members and using them with
synchronizing --> javac, please analyze object lifetime and garbage
collect local objects for me
- common expressions - declare variable of local scope inside a
loop; use repeative and verbose expression to express an algorithm -->
javac, please factor object allocation out the loop and precompute
common expressions (loop invariants) for me
- constant expressions - do not precompute complex math or
concatenate long strings --> javac, please precompute constant
expressions for me
- anything listed here
Rules of Optimization:
Rule 1: Don't do it.
Rule 2 (for experts only): Don't do it yet.
-- M.A. Jackson
More computing sins are committed in the name of efficiency (without
necessarily achieving it) than for any other single reason - including
blind stupidity.
-- W.A. Wulf
We should forget about small efficiencies, say about 97% of the time:
premature optimization is the root of all evil.
-- Donald Knuth