Þ   briarpig  » code  » thorn  » style

     The word style means a lot of things. This column is mainly about the manner in which code is written.

     My work style is rather different from what you'll see in code on this site. This site isn't representative of day job code style.

     In programming, the first rule of style is usually consistency, which means you should use the same style as everyone else so it all fits and all folks can read code effectively. Uniformity is good. At work I write as much like my coworkers as feasible.

     Work code style is also more verbose and oriented toward clarity in reading, since code is read more times than it is written. The code style used here is more write-centric, favoring how long it takes me to code. Less time is better. This is one reason I expect þ to be cloned when used in work environments: to fit normal work conventions in code style. Since I expect this, I worry even less how þ looks for work use. It won't be used — clones will be: clones in better style.

     (If you get stuck using code written in style you find here, I apologize in advance. I didn't think anyone would do that.)

     The code style I use here aims for brevity in exposition.

     So there will be short names and less whitespace, and everything will be scrunched in space to fit narrow columns. Pretend it's a fantasy lesson in code on a blackboard, where space is at a premium, and tight notation matters like in math.

     As mentioned on the names page, you should expect truly, obnoxiously short names for classes, member variables, and member function names. I treat names as arbitrary. I'm always happy to coin odd names when they make a story shorter.

     You might hate the short names. I think folks who see code as narrative miss long names like sentences as a cue to memory. If you're someone like this, I hope you suffer. (I'm kidding.) You might want to read another site if this is too irritating.

     I type a lot at work, and we use a longer, conventional style. I save myself for that. Your glass is half full, not half empty.

     I plan to make most of my material revolve around demos where code is motivated by trying to get something done. The demos might seem contrived at times, but real work is like that too.

     But I'll go on more side excursions than necessary; some content will rate as you aren't gonna need it (yagni) excess.

     Interfaces of many þ classes will just union every pragmatically useful effect needed over time, with conflicts resolved at need. This is a very casual and pragmatic style. If you need more design than this, you can work it into clones you write yourself.

     I use more careful design in APIs I worry might confuse folks. But þ is going to be mostly trivial stuff. If you find it confusing, I can't afford to spoon feed it using design drama.

     When possible, I try to make names unique under future search, but I'm not obsessive about it. I often factor and modify systems in ways requiring I find and study every single occurence of some set of code symbols. So it's good when different (say) member vars in different classes have different names.

     This is one reason I prefix class members — variables and methods both — with some kind of distinguishing element: usually part of the class name (the last letter or two in the class name). It greatly reduces false positives in manual search.

     I also disambiguate symbols this way because it avoids collisions when two or more classes mix namespaces by inheritance. Very similar things (such as methods for the same purpose in two different abstract APIs) can mix and not collide names.

     Much of þ aims to see whether code acts as expected. Printing objects — or data therein — is a typical inspection technique: really just debug printing. Standard C library file i/o is favored, to minimize use of higher level C++ APIs.

     Demos informally print results in human readable form, when taken as far as actual testing. Some demos won't include tests. Absence of error messages is a first sign of success. When counting errors, zero returns show a pass/fail status.

     thorn: todo, names, fd, iovec, assert, log, run, hex, crc, buf, in, out, quote, escape, compare, file, deck, cow, arc, blob, tree, slice, rand, time, stat, hash, heap, node, primes, page, book, pile, stack, atomic, lock, mutex, thread, map, meter, list, iter, ctype

     (mu: toy, peg, imm, tag, box, symbol, token, number, bigint, class, method, reader, writer, eval, env, vm, gc, world, pcode, compiler, asm, lathe, lisp, smalltalk, design, weight, jar, card, harp, debug, profile)

     Some demos are stubs: todo is a demo guide. See toy for mu updates on language pages; names introduces naming schemes.

     I'm rather casual. There's almost certainly philosophical reasons for it in addition to personality factors, but it all amounts to mental outlook. For whatever reason you like, I'm not careful about looking polished and complete in my presentation of ideas. You might get frustrated if you wait for total closure with all loose ends squared away. This is your cue to expect less polish; you won't get much.

     From my perspective, polish is expensive. Getting closer to done from every angle has diminishing returns. More and more words pile up with marginally less effect at the end. Thus I'm mainly interested in doing introductory parts, leaving completion as an exercise for the reader. Feel up to it today? Limber up and work out.

     From your perspective, I'm little concerned for your opinion, so I don't try to impress you. It might seem I'm slighting you, as if I don't respect your prowess in tech stuff. There's something to this, since I take a high level of competence for granted as prerequisite for getting on the ride. Being bright is just table stakes. I'm never interested in display, rank, competition, and status, so I rarely heed them at all.

     Fiction discussing tech appears several places, often with little or no warning. To the extent this is rarely done — mixing fiction and non-fiction in one place without division — it might look bizarre. But you should guess a casual attitude means I don't mind.

     Think of it as complimenting your intelligence. I expect you won't get confused because you're smart. You rule.

     I read literature on language acquisition as a teenager, and it reported young kids who knew several natural languages rarely got even slightly confused about which was used at any time. It was obvious.

     You watch television programming all the time where characters mix and interleave unrelated topics, and you deal with that easily. You won't have a problem. Just enjoy any funny parts you see.

     I often illustrate code with figures like the one below, which comes from my standard code to intersect two byte ranges in memory:

     By using ascii art plain text figures, I can easily embed these in source code where they explain otherwise confusing code. (I sometimes write methods that can't be grasped without figures.)

     I could draw nice jpeg images of figures instead that are easier to understand — and I might one day for fun. But figures inlined as comments in source code is a big advantage.

     This site would look fancier with good images, but that would also run up my traffic, and take time from writing docs.