Rules for making good APIs

There's an interesting article written by Michi Henning in CACM 05/2009 vol 52 no 05 API design matters. In this article the author shows some examples of "bad" API as well as its "remedy".

Here his recipes to write good APIs:

1. An API must provide sufficient functionality for the caller to achieve its task. Here, the author emphasizes to make sure that nothing is missing.
   
2. An API should be minimal, without imposing undue inconvenience on the caller. (well, that's not easy unfortunately :-(
3. APIs cannot be designed without an understanding of their context. In the other word, the API designer needs to imagine some use cases: if there's something unexpected, do we need to throw an exception ? or just return null ?
4. General purpose APIs should be policy free, "special purpose" APIs should "policy rich". The author suggests that if the context is unknown (case of general purpose), we can use the strategy pattern.
5. APIs should be designed from the perspective of the caller. This is clear, but not easy though.
6. Good APIs don't pass the buck. Don't add extra parameters if we are not sure !
7. APIs should be documented before they are implemented. We have to be more disciplined.

I personally agree with the author. As a programmer, it is much easier to write bad APIs than the good ones.

Xterm Title Bar Manipulations

An interesting code from Bash Prompt HOWTO: http://tldp.org/HOWTO/Bash-Prompt-HOWTO/xterm-title-bar-manipulations.html

function proml
{
case $TERM in
    xterm*)
        local TITLEBAR='\[\033]0;\u@\h:\w\007\]'
        ;;
    *)
        local TITLEBAR=''
        ;;
esac

PS1="${TITLEBAR}\
[\$(date +%H%M)]\
[\u@\h:\w]\
\$ "
PS2='> '
PS4='+ '
}

This code works so far on major *NIX console. There are some other shell script manipulation, but this one works nicely for me.

CSS template

In order to create a website, it is always a good idea to take an example from free templates then adapt them (if legal). There are tons of free template, but currently I found some elegants:

* http://icant.co.uk/csstablegallery/ that has list of template for table
* http://www.solucija.com/home/css-templates/ contains only some free templates, but most of them are very elegant.

Taking a template as a starting point is a lazy way to do, but it helps me a lot if you are not familiar with web design.

HTML and CSS Validator

I found interesting and useful links concerning validator for HTML and CSS. These links are taken from the signature of Stan Brown (no idea who he is).

HTML 4.01 spec: http://www.w3.org/TR/html401/
validator: http://validator.w3.org/
CSS 2.1 spec: http://www.w3.org/TR/CSS21/
validator: http://jigsaw.w3.org/css-validator/
Why We Won't Help You: http://diveintomark.org/archives/2003/05/05/why_we_wont_help_you

Cheap Webhosting

Looking for Unix/Linux based cheap but full of feature functionalities ? I have searched for reliable-cheap-and full feature webhostings, and until now, I can recommend two companies: routhost and integrahost. The former is highly recommended if the budget constrant is a high priority. Routhost can host your website with only less than US$ 3, with unlimited database, subdomain and email. However, if you have any problem or need a technical support, they only have ticketing system. This means there is no interactivity with the technical support.

Integrahost is a bit more expensive but very reasonable: less than US$ 8/month. They provide less generous functionalities but with more domains to be hosted. What I like from Integrahost is their technical support with live chat. Direct tech support like this for me is A MUST. For this reason, Integrahost is more preferable than Routhost if you have $5/month in your budget.
Integrahost also supports an affiliates program. This enables you to earn money if someone sign-up based on your affiliation.

Cheap website
List of highly recommended cheap website with nice feature and support

New Messenger with Voice

I just discovered last night that Yahoo and MSN messenger are now equipped with PC-to-PC calls (see the YM voice page). This feature is not only free but surprisingly has high quality of voice. Much more surprising for me, the Yahoo messenger now is available both for Windows and Unix/Linux version ! Apparently Yahoo understands that Unix/Linux community is not small and needs to be considered seriously.
Don't ask if MSN will support Unix/Linux environment...

So why all this free stuff for chatting and PC-to-PC calls ? Apparently Yahoo considers seriously the number one threat in search engine: Google. Since Google aggressively attempts to attract more people to join their community via Google's groups and Google mail (gmail), Yahoo has changed a lot.
Right now, Yahoo and MSN messenger are a step ahead compared to Google Talk.

Installing Acrobat reader on Debian

Due to license restriction, Debian does not provide Acrobat Reader package in its distribution. Fortunately, there is a work around to install the software "properly" (taken from http://www.bxlug.be/en/articles/128 and http://ubuntuforums.org/archive/index.php/t-1832.html):

1. Modify /etc/apt/sources.list file by adding:
   

deb http://archive.ubuntu.com/ubuntu/ warty multiverse

2. Then try to execute the following commands:

sudo apt-get update

3. This may contain some errors. We can ignore it. Last by not least, download and install the software:

sudo apt-get install acroread mozilla-acroread

Done ! Try execute the command acroread. If everything is fine, it will show the Acrobat Reader.

Presentation slide with Latex

Using Latex for presentation slide ? It may not be very obvious, but it can be very helpful if we have papers/thesis in Latex and want to reuse it. It is also helpful to cite with existing Latex bibiliography database.

Currently I only use two kinds of Latex presentation packages:

• seminar; and
• beamer

The first one is very simple and easy to work with, while the other is very advance, beautiful template and a little bit too automatic. With the first one, you have everything in your control. Thus, if I want something simple and fast, I'll use the seminar package, while for serious and advanced presentation I use beamer. I heard PowerDot is a very simple but powerful package. It may worth to try.

notes: Do not forget to run texhash or mktexlsr to rebuild Latex database

Computer and personal stuff

Computer and personal stuff

Callgraph for your application

I always wonder how my program looks like, what is the relationship between the subroutines, and is there any dead code. I wrote a tool to display callgraph based on gnu profiling (gprof) so not only it displays routines caller-callee relations, but also the time spent in each routine. The tool is written in tcl/tk and uses VCG format as the output. So far, I am quite pleased with the tool, and I hope I can make it publish soon. Currently I submit a new project to sourforge for this tool. A possible name for the project is cgprof.

Recently, I found out there is a very similar tool but more convenient. It is more convenient because I don't need to recompile or run my program. The tool is called nmDepend, a callgraph dependent graph that is based on posix/unix nm command. A similar tool for .Net is: nDepend. The former uses Graphviz as the output while the later seems uses their own format.

The three tools: cgprof, nmDepend and nDepend are similar. They all avoid parsing a source code which can be too language dependent and hard to code.

Website design

Looking for a free web template ? Finding a simple template with good Xhtml and CSS, plus simplicity is not easy. But thanks to Open Source Web Design, we can choose free (or almost ?) and open source template.
Most of the templates are well written and clean. It is a good think to see their template first before you create your own.