Monday, October 30, 2006
Use the source, Luke!
Ever spend like 15 minutes - or more than an hour, even - trying to figure out how some fairly complex API was supposed to be used - when what you wanted to spend was just 5 minutes of coding?
Well, I have.
Nowadays, if you are programming in Java - you do not have to do that anymore.
You can look up Javadocs describing an API and code samples of it actually being used in seconds.
Here are some very useful resources in that regard:
Note that I also have these in my blogroll in the sidebar of this blog.
I have used these more than a couple of times in the past few months. They save me a lot of time.
Once or twice recently, I worked out how to do something on my own - construct this factory factory, then use it to create this factory, then use it to get one of these objects, then use that to get one of those objects... - then later discovered the same thing spelled out at one of these sites.
I would much rather have something like that spelled out for me and just read it, than work it out by looking things up all over and then pulling it all together myself.
Using these services raises some hackles.
Sure, you can write it yourself - and you should.
That is not what these services are for doing. They are for showing you how the APIs are intended to be used. That is the point of using them.
Sometimes it is just plain simple how to do something. In other cases - it is not. Or, you have to read a lot of documentation just to get to the
So, that is the point.
Read the documentation, sure. That is how you learn the big picture, the caveats, the constraints, and the fundamentals of an API.
But to find intended usage patterns - sometimes the supplied docs are not the best. Sometimes they are the worst. Examples supplied with a Java library and JVM help - do not overlook them. However, these search sites are another tool to include in your toolbox.
Bookmark them and use them whenever the need arises.
Note that Firefox search add-ons are available for most of them. You are probably using Firefox, so grab them. Then you have them at your beck and call with barely a half second delay.
Well, I have.
Nowadays, if you are programming in Java - you do not have to do that anymore.
You can look up Javadocs describing an API and code samples of it actually being used in seconds.
Here are some very useful resources in that regard:
- Google Code Search open source code search
- Koders open source code search
- Codehound Java source code search
- javadoc online public source code search
- docjar open source code search
- Java Almanac APIs and examples
Note that I also have these in my blogroll in the sidebar of this blog.
I have used these more than a couple of times in the past few months. They save me a lot of time.
Once or twice recently, I worked out how to do something on my own - construct this factory factory, then use it to create this factory, then use it to get one of these objects, then use that to get one of those objects... - then later discovered the same thing spelled out at one of these sites.
I would much rather have something like that spelled out for me and just read it, than work it out by looking things up all over and then pulling it all together myself.
Using these services raises some hackles.
Is it for copying?and
You cannot write it yourself?
Sure, you can write it yourself - and you should.
That is not what these services are for doing. They are for showing you how the APIs are intended to be used. That is the point of using them.
Sometimes it is just plain simple how to do something. In other cases - it is not. Or, you have to read a lot of documentation just to get to the
Eurekamoment where you go:
Aha! I have used an API that was almost exactly the same as this before - I see what they are doing!
So, that is the point.
Read the documentation, sure. That is how you learn the big picture, the caveats, the constraints, and the fundamentals of an API.
But to find intended usage patterns - sometimes the supplied docs are not the best. Sometimes they are the worst. Examples supplied with a Java library and JVM help - do not overlook them. However, these search sites are another tool to include in your toolbox.
Bookmark them and use them whenever the need arises.
Note that Firefox search add-ons are available for most of them. You are probably using Firefox, so grab them. Then you have them at your beck and call with barely a half second delay.
Comments:
<< Home
Hi John,
Good post about using public code as a reference. I've found that many programmers confuse code search with "script kiddie copy & paste", so they don't view it as a tool for professional developers.
There's also the benefits from finding a component/project that can be used as-is or with minor tweaks - can be a really big win.
I had a good conversation with Frank Sommers at artima developer about some of these same topics.
Good post about using public code as a reference. I've found that many programmers confuse code search with "script kiddie copy & paste", so they don't view it as a tool for professional developers.
There's also the benefits from finding a component/project that can be used as-is or with minor tweaks - can be a really big win.
I had a good conversation with Frank Sommers at artima developer about some of these same topics.
I somehow left off krugle.com.
It searches source code of a great number of projects for whatever text you type into the search field.
I like it a lot.
It searches source code of a great number of projects for whatever text you type into the search field.
I like it a lot.
kenk,
I know where you are coming from.
The same thing - what I have always referred to as copy-and-modify - is big problem when people reach for existing code in the very system they are modifying too.
The longer the run of lines of code are that you are looking at, the less likely they will fit into your program.
The code may have flaws in it too. Copying it just multiplies the number of flaws in the overall program.
If a programmer has not read the API docs and the specs for the library or framework he wants to use then he will miss that. He will not notice that it is really an awkward fit.
If a programmer has read all the relevant documentation but something was not clear, often looking at a good example from a working program will help realize something he missed when he read the documentation. And that is what examples are for, right?
I agree that copying examples is usually the wrong thing to do. Using examples to sharpen understanding is what they are for, right?
Post a Comment
I know where you are coming from.
The same thing - what I have always referred to as copy-and-modify - is big problem when people reach for existing code in the very system they are modifying too.
The longer the run of lines of code are that you are looking at, the less likely they will fit into your program.
The code may have flaws in it too. Copying it just multiplies the number of flaws in the overall program.
If a programmer has not read the API docs and the specs for the library or framework he wants to use then he will miss that. He will not notice that it is really an awkward fit.
If a programmer has read all the relevant documentation but something was not clear, often looking at a good example from a working program will help realize something he missed when he read the documentation. And that is what examples are for, right?
I agree that copying examples is usually the wrong thing to do. Using examples to sharpen understanding is what they are for, right?
<< Home
