Watched a google video by Joshua Bloch on "How to design a Good API". Great nuggets, something all should listen to every few years.
1. Start with Requirements and a short Spec (one page is ideal)
Man, I do agree with this. When I see a requirement doc coming which is more than a page I get nervous. But he also reflects on a what a requirement is and promotes thinking in generalization rather than fixed implementation. Very important for API developer, but to his point important to all developers. He does caution on overusing this principle to justify over engineering.
2. Prototyping good. Write Plugins. Write Example Code.
Code early, Code Often. Nothing better than doing.
3. You need a lead!
APIs can get over constrained, over engineered, designed by committe, and just plain messed up without direction and decisions. You need an architecture and architect to make decisions and now when to commit.
4. Real world use will flush out bad.
Hmm... it will also at times propagate bad behavior. And he does suggest that as well. I do think there is a whole in his thought process as it relates to longevity of platforms and APIs. I think that whole is that one constraint is time.
5. Name everything as long and obfuscated as possible.
Ha.. Just getting your attention. Of course he said name it simple, name it smart. Code should read for a 5th grader.
6. Document Religously for Reusability
Not sure I agree with this one in absolute. I think someone who documents sets the right tone and probably delivers better code, but I don't think that drives adoption/reusability. Too many things we all use has NO documentation. Though, I 100% agree better documented is probably just better code.
7. And as he suggest the biggest nugget (and I agree) "When in doubt leave it out".
My background and experiences have me brain-trained in this, once an API is published it's there for life. The CTO I worked with at Bluestone software had a straightforward approach to enforcing this: Change an API and you must change your name on every document you every created since birth, once that is completed you can change the API.
All in all this should absolutely be taught in high school computing as part of the basics.
Many more nuggets to review, but here are some other links and blogs about the topic
Blog Search
No comments:
Post a Comment