picture home | pixelblog | qt_tools

omino code blog

We need code. Lots of code.
entries for category "broad generalities"
David Van Brink // Thu 2014.04.10 13:17 // {broad generalities code}

Code Connectivity

Thought of the moment.

There are levels of interconnectedness…
Level 1 — basic — compiler knows they are the same. Command-click or F12 finds it…
Level 2 — intermediate — strings match. grep -r can find it…
Level 3 — majikal — you have to know something about some rules for construction…
Level 4 — arcane — you just have to know.

It’s nice to hover around Level 1 or Level 2.
If you’re in Level 3 or Level 4, maintenance is… challenging. But can be slightly mitigated if you can create a unit test or build step that, somehow, confirms that everything is lining up.

oh, i dont know. what do you think?


David Van Brink // Mon 2008.10.13 08:57 // {broad generalities future}

Free Idea: New International Power Plug

This morning I woke up doing some dream-design work.

It was about the new international standard power plug. It resembled an American power plug, nonpolarized. The tines were a little bit more widely spaced, and narrower.

The power cord was a little bit thinner and more flexible than normal cords. This was for two reasons. First, the AC current on it was stepped in some exotic way that allowed more effective power over the same conductors than a pure sine wave. Maybe it spreads the frequency out more, and affects the cooling characteristics.

More importantly, the voltage and frequency was negotiated by a tiny chip in the plug itself, with the wall outlet. It’s down in the plug, again, to optimize cord weight.

Presumably the protocol can also carry data.

I’m pretty sure the stuff about the frequency-spread and power capacity makes no sense at all. I am just a software guy. But the rest seemed plausible enough. I do so hate wallwarts.

oh, i dont know. what do you think?


David Van Brink // Tue 2008.09.30 17:01 // {broad generalities java}

Practical API Design by Jaroslav Tulach

Found and acquired this book today at Bookshop Santa Cruz. Very nice tome on good Java API style. Alas, slightly pricey ($75 retail). The fellow’s a bit ranty at times… but, ah, I can relate. The author was a founding architect of NetBeans , and is still a principal on that project.

Also, look, google lets you embed a book for up to 20% reading! (Embedded below, may take a moment to load.)

Search for “beatiful” or “symmetry” or “backwards compatibility”…

oh, i dont know. what do you think?


David Van Brink // Thu 2008.06.12 09:17 // {broad generalities code}

Code Velocity Profile

  1. A body of code is never finished
  2. The authors have in mind some “next steps”
  3. The code implicitly supports these particular next steps, and similar ones
  4. The code implicitly hinders wildly different next steps
  5. Adoption by users implicitly supports the current state and, depending on apparent paradigm, supports the intended next steps
  6. Adoption by users resulting in persistent manifestations of the current state — that is, saved documents — explicitly hinders wildly different next steps
  7. Intermittent development may distract from those next steps, but they are still implied by the code (and the current state is required by extant persistent documents)
  8. Development by new authors may distract from those next step, but they are still implied by the code (and the current state is required by extant persistent documents)
  9. If you accelerate for six months towards the wrong star, it takes 18 months to turn your spaceship around, decelerate, and return to your starting point at a stop. Less if you don’t mind overshooting.

Seems about right.

Compelling charts and graphs omitted.

oh, i dont know. what do you think?


David Van Brink // Thu 2008.05.22 12:17 // {broad generalities future}

Free Idea

This morning my girlfriend had to get up at 4am to catch a flight to Arkansas. After seeing her off, I dozed and had some abstract dreams, which eventually crystalized into a design meditation for a ludicrous web 2.0 product.

Ludicrous? You decide. Let me know if you get rich with it.

The general concept is an “active DVD player”, active in the sense of “active viewing”, as parents are encouraged to promote with their kids’ tv habits, this for example.

This active player will of course devolve into trash, but that’s besides the point.

The idea is that while watching a particular bit of content, you can search or skip around in it, using various annotations. Obviously, you can search on the existing subtitle stream (once it’s been OCR’d). You can contribute to the searchability by annotating any part of it. You can add notes, describe images or frames, or other remarks Naturally, this is put in a big huge shared database, categorized and rated perhaps by whuffie.

And of course you can choose to chat with others who happen to be watching the same thing at the same time. You get the idea.

Copyright issues are for now sidestepped by only supporting physical DVDs in the player; the shared annotations contain only frame-number references.

Annotations are for now keyed to particular DVD’s, since different editions and edits will have different frame affiliations. Tragic but true. Perhaps later the annotations can be regathered by image-matching or globally-unique-timecode markers. (GUTM’s will be necessary moving forward for rights-management and tithing on fragmented media; we’re certainly near the end of the age of the personal library.)

Just imagine when every frame of every movie is a potential match on Google image search! After we run for a few years, the dataset will be worth billions. Go, Team Crowd!

But isn’t this grotesque, providing yet another outlet for mindless dotery on the creative work of others? Well, yeah, sure, I guess. But I think we have to accept that our imminent “nation of artists and philosophers” is actually evidenced by the fact that Wikipedia has a longer article on Darth Vader than on Klein bottle, dobsonfly, or Charles Babbage.

oh, i dont know. what do you think?


David Van Brink // Tue 2008.05.13 18:34 // {broad generalities software architecture}

Deltas

I don’t know what this means, really, but it seemed really profound when I wrote it on my whiteboard. But now it’s time to erase the whiteboard, so, here it is.

Something about the plugin manager and some recent “improvements” to it…

oh, i dont know. what do you think?


David Van Brink // Mon 2007.12.17 10:13 // {broad generalities code}

Dear Plugin Developer

Dear Plugin Developer,

Always code defensively. Assume the rest of the system is insane, and your module a small island of clarity, nay, robustness, in a sea of unreason.

We do NOT guarantee to call any interfaces or API methods in any particular order. We do NOT guarantee even to set only legal parameters! (This is because “we” are not always GooEdit, “we” are scripting clients, other editing hosts, anyone with a compiler might eventually call your plugin, joining the ranks of “we” to your “they”.)

On the flip side, we bulletproof GooEdit against plugins throwing exceptions, returning absurd results, and so on.

So!

The interface you were asking about is ISetMoreInfo. And sometimes the value will be “null”.

–> Goo

oh, i dont know. what do you think?


David Van Brink // Fri 2007.10.26 18:32 // {broad generalities code}

Basics: Write Short

Code comments and email subject lines should be as short as possible, and no shorter. They don’t have to be full-featured English.

Basics: Write Short

In writing, brevity is a virtue. Samuel Clemens, responding to one particular excess, wrote: “Substitute ‘damn’ every time you’re inclined to write ‘very’; your editor will delete it and the writing will be just as it should be.” There appears to be a misperception that great meaning requires lengthy prose; but to misuse Yoda’s words: “Size matters not.”

The title of this post was “How to write short”, then “Please write short”, and, finally, “Write Short”. Brevity is of especial importance in code. Other contexts of critical brevity include:

  • code comments
  • email and bug-report subject lines
  • blog posts

Code: Get Rid of Of, and And, and To, Too

(I’ve noted some of the patterns, but I suspect my nomenclature is flawed. Improvements welcome.)

nameOfPort should be portName (noun aspect pattern)

getNumberOfFish() should be getFishCount() (verb aspect noun pattern)

saveIfNecessary() can be maybeSave() (adv verb pattern, & your reader can trust you)

addFishToPond() should be addPondFish() (verb dest source pattern)

And my favorite: the_address_line_to_the_uart1 should be uart1_address (noun aspect pattern)

Code Comments: What, Not How

There’s plenty of available wisdom on comments; a veritable commentary of commentaries on the subject, even. I’ll offer just one example of comment shortness.

// set n to the number of fish

should be

// n is the fish count

How it happens is the code; what has happened may be worth a comment.

Email & Bug Report Subject Lines: Frontloaded Please

The important thing to remember is that email and bug report lists often appear in tabular form, with the Subject column truncated. Keep it short, and lead with the most important words.

Help!!! I opened the document and then selected the first block and it froze!

Should be…

Freeze after Open & Select-Block

And that’s enough of that. On to our last area of brevity…

Blog Posts…

Guilty, but I’ll try harder. Bye now.

oh, i dont know. what do you think?


An application typically stores its state as a file. As an application user, you expect this file to work, even if you don’t touch it for a while. This note offers some primal advice on implementing a file format in your application.

Basics: Know Your Document Format

Your Application’s Document

Be in control of your file format — it’s your most persistent API. Application versions will come and go, but you and your users expect the documents to last forever.

One lesson I’ve learned is simple: there are no shortcuts for mastering your own file format. You have to design it and implement it. By all means leverage existing parsers, such as for XML or RIFF or what not. But I honestly believe that there is no appropriate automation for translating your in-memory-model to a file format.

Tools like JAXB which generate XML serializing and deserializing code based on a schema can be quite useful, but I always add an additional translation layer between these generated classes and the “real” API.

Too Much Model

I’ve seen bad results from “built-in serializers”; one application developer I worked with relied entirely on the built-in serializer of Apple’s “Yellow Box” (this was essentially “Cocoa” running on Windows, after NeXT, before Mac OS X). Every build of the application produced a different file format, and some daisy chain of machine generated updaters was able to continue to read it in. The real problem was that we ourselves couldn’t reliably answer the question, “What’s in the file?”. We couldn’t easily write other tools to manipulate or debug our own documents, or stimulate test cases. (Staccato Systems’ “Synth Builder”.)

Too Much File

At the other extreme, I’ve seen bad results from reading an hierarchical file structure into memory, and attempting at all times to keep it identical to its on-disk representation. This required a lot of work, and bugs manifested as extra data in the file which other readers just needed to ignore. But not all readers ignored it, and so these stray file elements became de-facto parts of the file format. (Altera’s “SOPC Builder”, and its PTF file format, before our total overhaul.)

Just Right

It’s safest to define your file format separately from your in-memory model. They may be similar, but it’s valuable to implement the file reader and writer as a separate entity from your model. This will involve a translation layer where you read in your file format, perhaps to an in-memory tree structure of some sort, and then populate your in-memory objects. There are opportunities to make this more or less automatic, as appropriate to your particular development effort. But, importantly, this translation is very well-defined and therefore very testable.

Generally…

Hierarchy.

A file format will usually be hierarchical. That’s just the common design pattern that seems to cover the bases. As with your object design, it’s handy to make the hierarchy something that maps intuitively to the problem domain. This is easier said than done, but is an opportunity for artfulness… to say the least. As to the low level file format itself, in general in this day and age you can probably just skip any tedious meetings or debates and create an XML-based structure. If you need to store lots of binary data, and file size is a concern, your XML document can refer to neighbor files. And under no circumstances let the argument that XML is too user-unfriendly or heavyweight influence the decision; these remarks come from those who don’t know from Koolaid. Really.

No Redundancy.

The persistent document should capture each datum once and only once. As a thought experiment, imagine someone manually editing the file, perhaps even in a text editor. Ideally, they should be able to modify an entry in the file and have a predictable feature of the document change when loaded.

Human Readable.

And speaking of the above thought experiment… This isn’t always possible, and in rare cases is undesirable (for reasonable or less-reasonable reasons). But usually it’s a great benefit to be able to examine your document in a text editor. It’s great for debugging, that much I can promise. Another advantage of a text-based file format is it removes any questions of byte ordering or floating point format. What number is hex 01 02? You have to define whether it reads as 258 or 513. But if your file says “x = 258;” then it’s perfectly clear.

Easy In, Rigorous Out.

When reading in your document, be generous. If something is missing, insert a reasonable default value. This strategy can be used with cautiousness and, dare I utter it, cleverness to extend the file format and still be backwards compatible. On the converse however: Always write out everything! It is not safe to skip an entry because its value happens to be “the default”. Someday you’ll change the default, but old documents mustn’t change.

Be Careful With Scripts.

It may be tempting to use a scripting language as a file format. For example, TCL is very easy to embed in C or Java programs, but it’s not ideal as a document file format. Some will argue that philosophically code and data are the same thing. My counterargument used to be something about predictable computation time and the halting problem: if you read in a script, it might run briefly or it might run forever. But I have, I hope, an even more compelling distinction: code can erase your hard disk but data can’t. It’s that simple.

When I’ve seen scripts used as a file format, invariably, eventually, there exists some need to “parse” the script without “executing” it, which is of course absurd. If you depend on being able to parse a subset of the language then you’ve reduced it to data. Use a data format, not a scripting language.

Closing Remarks

One day in the far future (but sooner than you expect) it will be time to rewrite your application from the ground up, or create a new application which interacts in some way with the old one. In either case, a well-defined and knowable file format will render these tasks possible.

oh, i dont know. what do you think?


David Van Brink // Wed 2007.08.1 17:43 // {broad generalities code java}

Basics: Null and Nuller

I write a lot of code which other people call. One of the basic problems to wrestle with is: “How do I handle unusual inputs?” This note shall discuss some aspects of this, focusing on the use of “null”. Although the examples are phrased in Java, the ideas may be of general interest

Basics: Null and Nuller

Exceptions: An Inconvenient Shape

Opinions vary regarding the use of Java exceptions as part of an API. Most agree that they should be only used to indicate an “error”. But what exactly is an error? It depends solely on your definition of valid input.

In general, I prefer not to throw exceptions. I find it cumbersome to pepper my code with lots of try and catch blocks; I presume that you feel similarly. In general I’d rather check a result for “null” or “false” or some other indication of “what happened”. (This narrows the range of possible outcomes, which could be seen as limiting, but I prefer to think of it as simplifying.) To avoid throwing exceptions I try to define widely the range of valid input to my methods.

Toleration

In general, I try to make my methods tolerate, or even expect, null inputs. A null value for a parameter should be treated in the most innocuous fashion. If it’s an input, give it some default behavior. If it’s an output — such as a logger or list to be modified — let it do nothing. Return the best possible output.

As a result, I often have related convenience method variants like this:

public static void foo(String name) {
   foo(name,null,0.0);
}
public static void foo(String name,Version version) {
   foo(name,version,0.0);
}
public static void foo(String name,Version version,double scanTime) {
   ...do the operation...
}

Crash Your Code, Not Mine

Since you may not have access to my source code for debugging, I’ll try not to crash and instead push the problem back to your code. So, specifically, I’ll make sure that my method won’t ever fail on null; instead, I’ll do nothing, or return a null, so that your code will see the problem. Perhaps your code will crash; if so, you have your own source code to debug and correct. Also, in some cases, I’ll return a boolean which indicates “true” for “success”. It’s your option to read it, but is available as needed.

Return Null or an Empty List?

Some methods return a Array, List or Map, or similar objects, based on some input. If the input is all legal and normal but produces no results, I’ll return an empty list. That way you can iterate on it, check the size, and so forth, without any special case for “no results”. On the other hand, if some “necessary” input is null, I’ll return null to indicate that. Your code can then explicitly check it if needed.

Masking A Problem

The notion has occasionally been put forth that tolerant code hides errors. After all, it can be argued, if it fixes stuff up, one might think all is well. In general, I reject this claim. A method that accepts a wide range of possible inputs and has a well-defined behavior for them is simply doing as its told.

The situations alluded to where “tolerant” code hides a deep problem have, in my experience, been always linked to side effects. A typically terrifying example would be some innocent looking method thatlooks like a query but actually always fixes up your input document — just in case it was a little bit off. This is not “tolerant”, this is “toxic”.

Preflighting

How many times have you seen this code fragment:

    String s;
    int n;
    ...
    try {
      n = Integer.parseInt(s);
    } catch(NumberFormatException e) {
      n = 0;
    }

This lets any value of s, including null or a nondecimal value, evaluate to 0. But achoo, look at that try/catch peppering. I’ll always package that up in some tolerant parser. (And this gives a place to allow 0×123 or other numeric formats, if desired.) But sometimes you need to know if the input was rigorously acceptable, so we have a preflight method, as well.

    String s;
    int n;
    ...
    boolean formatGood = MyNumberUtils.isInt(s);
    n = MyNumberUtils.parseInt(s); // never excepts, 0 for bad number format or null

Neat and tidy! And all the information there, ready to steer the program as needed.

But That’s A Lot Of Bother

Hardening libraries against even these minor abuses takes effort. If some library is being used in many places, this effort — and much more — is well-spent. It offers value to every client. On the other hand, libraries always start out with zero users… but you have to start somewhere.

1 comments
weird of wbl // Wed 2007.08.8 05:565:56 am

when do we get the regularly scheduled weird blinking lights hardware experiments?

oh, i dont know. what do you think?



(c) 2003-2011 omino.com / contact poly@omino.com