Coding style. Nice idea. Well, if anyone asks...

There are two kinds of program code; machine code and documentation for
it. Binary machine "object" code is for machines; everything else is for
humans, and is thus documentation. A "language" like C is portable, so it
documents a virtual machine. The machine C programs is in it's code
generation stuff.

"readable code" is an oxymoron. So is "programming language". But you have
to try, or you might as well code in a binary editor. 

So what's "readable code" so far in this young craft?

Information can be correlated by proximity, or by reference. Proximity is
much simpler. Much. Thus, DO belabor names. Sweat over lucid names. Let
them come to you. Wait patiently for them. Good names makes assembly
viable, hence osimplay.

Tabulations are 9. ASCII 9. Spaces are ASCII 32. Whitespace is cheap. Tabs
are cheaper than spaces.

Auto-documentation of any form is a very low-data-rate thing. Most of it
is pure noise. Indentation should flow like a melody. It should dance
smoothly with the eye. It should breathe, invite, NOT be automatic, in
other words. Not entirely anyway.

Names have context, particularly in a big work. The context is part of the
name, and reduces the data required of the particular name to convey
itself completely. Just like dir/dir/file in a file hierarchy. When you
name something, do so "from the local dir" mentally. There's WAY too
little of this. Plan 9 errs on the side of locality, but conciously so.
Lacal variable names like a b c usually aren't all that bad. Globals and 
whatnot are another matter.

Intuitive=familiar. Names and so on don't have to be corny because they
are being fed to a computer anymore. They used to have to. Written English
has lots of nice techniques for conveying information. Reuse English; it's
familiar. Acronyms tend to be capitalized. Compound words are hyphenated.
Use underscore if you don't have hyphen. (unix name constraints suck.) A
word signifying a collection of things frequently has an s at the end of
it. This is called a "plural". What a concept. AH, but back to context, an
array name has an index, so it's "widget 3", not "widgets 3". Or "3
widget". "3 widgets" sounds like you are creating them, not simply
accessing them, i.e sounds like a verb when it's more like a compound
noun. Suffixes tend to map to part-of-speech categories. Re-use stuff like
that. Although indexing into an array is an action, the result of that
action is just a noun.

Comments are dynamic. They come and go as a project progresses. When a
work is presented to the outside world, then there should be enough
comments to act as a guide, but not as a crutch. Comments should be like
street signs. Good ones. They shouldn't obscure your view of the traffic
(i.e. the code).

A guru is intermittently a guru and a helpless naif all day long. That's
how they got to be a guru. Thus some things should be terse, that get used
all the time, and some things should read like
jump_but_NOT_fix_up_stack_frame_GOT_IT? if they are obscure and
treacherous.

Macros rename things. Why? Is "diskchanged" better than 0x80? Be sure it
is. Have a damn good reason for macros. Consider comments instead. At this
point I don't really know of any valid uses of macros.


These guidelines ALL have escape clauses. Use them also. The machine code
of a program is engineering. Everything else is for humans, and some warm
fuzzy is good. Unix docs tend to only document the precise thing being
documented, and harshly avoid contextual info. Context changes, but
usually a certain thing assumes a certain context, or is meaningless
without it, and thus context info can be useful.
