• Post Reply Bookmark Topic Watch Topic
  • New Topic

API design & naming conventions  RSS feed

 
Arnold Reuser
Ranch Hand
Posts: 196
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
The problem I face, actually already for quite some time now, is that during the design of an API I am forced to capture the functionality of a method in a short but meaningful way.
It amazes me that I often find myself spending more time on thinking about a suitable name for a method than on writing the actual code.
My main question : what are your best practices on picking suitable names during the design of your API? Do you use some kind of list of prefixes that you reuse over and over again or ....
[ June 07, 2008: Message edited by: Arnold Reuser ]
 
Ernest Friedman-Hill
author and iconoclast
Sheriff
Posts: 24217
38
Chrome Eclipse IDE Mac OS X
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
An alternative approach is not to design the API, really, but instead write some client code that uses the API before it even exists. In the client code, name the imaginary methods you're calling according to what they do from the client perspective. This is often called "programming by intention", and it often leads to APIs that are simple and intuitive to use.
 
Bear Bibeault
Author and ninkuma
Marshal
Posts: 66304
152
IntelliJ IDE Java jQuery Mac Mac OS X
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
In addition to what EFH said -- a practice I often employ -- I tend to use longer names that are descriptive, and I never freeze-dry words by removing vowels or any other characters.

If it's an event handler of some sort, I'll usually prefix it with "on" -- for example, onKeyboardHasCaughtFire. Factory methods start with "make": makeSuchAndSuch.

Of course, I adhere to JavaBean conventions for property setters and getters.

Otherwise, I usually start the method name with a verb describing what the methods does and to what: paintTheTownBlue.
[ June 07, 2008: Message edited by: Bear Bibeault ]
 
Pat Farrell
Rancher
Posts: 4686
7
Linux Mac OS X VI Editor
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Arnold Reuser:My main question : what are your best practices on picking suitable names during the design of your API? Do you use some kind of list of prefixes that you reuse over and over again or ....


Java is not C vintage 1990, there is no need for Hungarian notation.

Pick names that make sense, good IDEs can do expansion for you, so saving a few characters is not needed or even good. Think about the developer who has to use the code five years from now.
 
Arnold Reuser
Ranch Hand
Posts: 196
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Programming by intention seems to provide the knowledge I was looking for.
Many thanks for your feedback on this.
 
Dan Murphy
Ranch Hand
Posts: 126
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
There's a good chapter about naming of classes, methods, variables, etc. in Steve McConnell's book "Code Complete".
 
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!