Tuesday, November 13, 2012

If you have to refer to the documentation every time you use a module, find or build a new module

I recently checked out this slide deck called "Python For Humans" by Kenneth Reitz  which takes Python's Http library and rewrites it in a much more intuitive way. (I've used the Python http lib - it's not particularly straight forward). The deck is not really about Python, it's more about good API design. One of the slides says:


If you have to refer to the documentation every time you use a module, find or build a new module

Which I think can be generalised for API designers to 

If you have to refer to the documentation every time you use an API, change the API

This is excellent advice and something I could immediately apply to my own code. Even if you're using an API (rather than writing one), it's worth building an abstraction layer on top of the API you're using if it sucks - Win32 I'm looking at you :) I seem to vaguely remember in Win32 to move a window you have to call a function named ResizeWindow or something equally obscure. Anyway I looked at my own code and made a few changes. In Dancing Squid (my small game engine) my scripting API text alignment functions are called:

Renderer.SetFontAlignmentHorz and Renderer.SetFontAlignmentVert

I could never remember these function names, never - I always had to look them up! Also do you really align a font? Surely it's the text you're aligning?

It just seems a bad name all over. After reading the Kenneth's slides I decided at least this one part of the codebase needed a rename and I went for

Renederer.AlignTextX and Renderer.AlignTextY

Which I find far easier to remember - even as I was coding just now, and came to do some text alignment, I had a brief moment of syntax joy as I knew I'd be able to type out the functions without having to go to the docs or search my code. Good advice, that deep down we all know, but occasionally need reminding about!

No comments: