by Pavel Penchev
This was one of the talks I was looking forwards to, since I have had the pleasure of talking with Pavel before and I know he has a lot to share on this topic. However I was disappointed that this talk took place in a crowded and hot small room and the words of the lecturer was barely audible. A real shame, but fortunately I was able to catch some of the things he shared with us.
Writing public API as opposed to writing internal API
We have all faced the challenges of writing APIs to some degree - however the problem becomes much more complex once we have to actually sell a public API. Then the design of the code, it's documentation and naming conventions, all of the things we usually consider internal, become part what we would usually expect from our user interface, they became the face of our product.
The topics in this lecure were mostly influenced by two very well written books:
- "The design of everyday things" by Donald A. Norman - a book that is not strictly focused on software development but on the design of products as a whole
- "Effective Java" by Joshua Bloch - which is a book that every Java developer should seriously consider reading
"The API is a business card to your company"
A very crucial point is to use the terminology of your domain. Many times developers tend to look at their code from an implementation point of view and use names such as "SystemEntity", "DOMTree", etc. These names, although accurate, do not translate to the user the purpose of the objects but rather translate the implementation specifics, which is not important to the user.
"Your code needs to be easy to use, easy to learn, but also hard to misuse"Footnote : here is a good article by Joshua Bloch that I stumbled upon while writing this blog post on the same topic.