blog.s11n.net

Tip: Code Commenting

Hello, fellow hackers!

We’re all aware of the “dangers” of adding comments to implementation code, such as:

int x = 32; // default value was decided by committee...

In practice, comments tend become disassociated from their code, especially when more than one person works on the same code. For example, the following is relatively common in real-world code:

// default value was decided by committee...
int y = 7;
int x = 32;

With that change, we’re not really sure which default value the comment is referring to.

Recently i stumbled across a commenting approach which has helped me avoid this type of problem:

int x = 32 /*default value was ...*/;

Note that the comment is inside the statement, before the semicolon. The side-effect of that is that coders who edit that line are much more likely to have to deal with the comment. For longer comments, it helps to split up the lines:

int x = 32
  /* default value was ...
     on 20101214 ... by ....
   */
;

Again, the comment is inserted as part of the statement. If someone wants to move that line, they’ll be forced to acknowledge that “something unusual” is happening, and are likely to read the comment to figure out what’s standing in their way.

It’s a simple to apply approach which i’ve started using in all my code, and i nowadays i recommend it as standard-practice over adding comments in the more conventional forms:

// before the code:
int x = ...;

int y = ...;
// ^^^^ after the code, with carets meaning "look up to the previous line"

int z = ...; // after the semicolon

Happy Hacking!

—- stephan beal

PS: there are people out there who despise any form of comments, and i was once told (on a popular open source project) that having comments in my code contributions made an “unprofessional” impression. You may disagree that comments are useful/necessary/whatever in code, and that’s fine. Let’s just agree to disagree.

Update on 2010.12.20: some of you will simply laugh and say, “my programming language of choice doesn’t use semicolons” or “my programming language uses semicolons as comment markers!” To you i say, “how sad!”

New Article: Doing OO in C

Good evening, fellow hackers!

While i tend to write absurd amounts of technical documentation, mostly in the form of API docs and other code documentation, it’s been several years since i’ve published a technical article.

For those 5 or 6 remaining aspiring C programmers in the world, i’ve got a new article which demonstrates a useful 999(shit, my left shift key just quit working…)… ahem… demonstrates a useful (in my opinion) model for implementing object-oriented data structures and APIs in C. DAMMIT, AND NOW MY ENTER KEY BROKE!

(thank god for the numeric pad’s enter key…)

Since my keyboard just died, i’ll keep this short… the article is here:

http://wanderinghorse.net/computing/papers/

happy hacking1

9you never truly appreciate the left shift key until it’s gone…0

—– stephan beal

Update:

LOL! (i’ve now got my backup keyboard…) At the very same time my keyboard broke i began being affected by this new Google Chrome bug:

http://code.google.com/p/chromium/issues/detail?id=66071

(Short version: mouse wheel cannot scroll up, but can scroll down.)

i thought, because my keyboard and mouse (in Chrome, anyway) weren’t working, that maybe my USB bus was dying.

On-storage Hashtable in C

Hello, C hackers! (Everyone else can skip this post!)

For a couple years now i’ve been maintaining a project called whio, the wanderinghorse.net I/O library for C. In short, it’s a collection of input/output APIs for working with sequential streams and random-access devices. It allows one to wrap a variety of lower-level I/O APIs (e.g. standard FILE handles or file descriptors), or implement custom ones, behind a uniform interface. Over the years it has grown to include a good deal of functionality.

i’ve spent a good deal of time looking for and investigating storage-based hashtables for C over the years (B-trees as well), and have found depressingly few of them (and none which i could drop in and re-use without modification). The few i did find were limited to using C-standard FILE handles as storage, and FILE handles don’t always suit my I/O needs. The whio_dev API has several different device implementations, not just for files, and i wanted a hashtable with that flexibility. So of course i had to write one myself ;).

A few days ago i added a new API to whio, called whio_ht, which is an on-storage hashtable.

A very brief summary of its properties:

• Insertion, searching, and removal are all amortized O(1). This means that the time it takes to insert, search for, and remove records is essentially independent of the number of records in the hashtable.
• Constant memory usage of less than 500 bytes. (There is one exceptional case involving “really long” keys, but it is not expected to that most clients will fall into that category.)
• Can use any storage back-end for which we have a whio_dev implementation. e.g. it can be used with a memory buffer device or embedded as a pseudofile within a whio_epfs container.
• Data file format is platform-neutral. Encoding of keys/values, if necessary, is left to the client.
• Supports arbitrary key types, provided the user can supply hashing and comparison functions for them. The library includes routines for hashing/comparing strings and the standard fixed-sized integer types (from stdint.h).

If you’re still looking for a storage-based hashtable API in C, whio_ht might just be of interest to you.

Happy Hacking!

—– stephan beal