Co[de]mmunications

Programming and ramblings on software engineering.

Tangled Up in Tools

On what’s wrong with libraries, and what to do about it.

The simplest thing that we can do right now is to rethink how we document libraries. Automatic documentation tools like Javadoc and Rdoc are good for producing thick stacks of paper, but not so hot at actually telling library users the things they need to know. They are the source of most of the world’s “newRecordAddedHook is called when a new record is added” documentation. They can be useful, but they are no substitute for actually writing about the library: single-page summaries that answer the three key questions: what the library does, why you should use it, and how to do so. For bonus points, the one-page summary should avoid using the word “enterprise” (unless it’s a library of Star Trek ships) and “innovative.”

Software Bugs

The only difference between a bug and a feature is the documentation.

Source unknown.

Über Programmers

The romantic image of an über-programmer is someone who fires up Emacs, types like a machine gun, and delivers a flawless final product from scratch. A more accurate image would be someone who stares quietly into space for a few minutes and then says ‘Hmm. I think I’ve seen something like this before.’

The Goal of Computer Science

The ultimate goal of computer science is to help produce better systems. Would you trust someone who had not seen a patient for years to teach surgery? What would you think of a piano teacher who never touched the keyboard? A CS education must bring a student beyond the necessary book learning to a mastery of its application in complete systems and an appreciation of aesthetics in code.

Software Reuse

On the problems with object oriented languages and software reuse. Joe Armstrong created Erlang.

You wanted a banana but what you got was a gorilla holding the banana and the entire jungle.

Real VMX QEMU Script

A script for people who want to develop for Real VMX, a VxWorks-like operating system kernel. The script installs ext2, GRUB, and a vanilla kernel to a small (32 MiB) QEMU image.

Real VMX running in QEMU.

Some features of Real VMX:

  • Priority-based multitasking and round robin scheduling
  • Partition-based memory management
  • Binary and counting semaphores with priority-inheritance
  • Message queues for inter-process communication
  • Virtual memory

Real VMX is licensed under the LGPL.

Get the script here! (only tested in Linux)

The Use of “do { … } While (0)” in C Macros

Consider a countdown program.

countdown.c:

#include <stdio.h>
#include <unistd.h>

int main(int argc, char **argv)
{
    int seconds = 3; 

    for (int i = seconds; i != 0; --i) {
        printf("%i... ", i);
        fflush(stdout);
        sleep(1);
    }
    puts("Go!");

    return 0;
}

The goal is to put the actual countdown code in a macro. It fits perfectly in a function, but a macro is used for illustration purposes.

Using Javascript to Provide Dynamic Content in Tumblr

This article describes how content can be added to Tumblr using Javascript, and the jQuery library. The reader should be familiar with web development.

A Simplified Theme

<html>
<head>
  <title>My Tumblr</title>
  <script type="text/javascript" src="http://example.org/jquery.js"></script>
  <script type="text/javascript" src="http://example.org/tumblr-dyn.js"></script>
</head>
<body>
    {block:Posts}…{/block:Posts}
    <p id="quote-of-the-day" style="display:none"></p>
</body>
</html>

We shall add a quote to #quote-of-the-day for permalink views.

tumblr-dyn.js

var isSinglePostView = function() {
    var loc = document.baseURI;
    var re = new RegExp(".*mytumblr.example.org/post/.*");
    return loc.match(re) != null;
}

$(window).ready(function() {
    if (isSinglePostView()) {
        var qotd = $("#quote-of-the-day");
        qotd.html(
            '"You should\'ve seen the look on her face. It was the same look ' +
            'my father gave me when I told him I wanted to be a ventriloquist."' +
            ' – George Costanza');

        qotd.css('display', 'block');
    }
});

You can use this approach to add custom content depending on what page the user is viewing.

Configuring an SSH Gateway

An SSH gateway can be used where multiple hosts share the same IP address, where it isn’t possible, or acceptable, to use separate ports for the hosts’ SSH daemons.