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:
Post a Comment