The Benefits of Having the Source Code for Libraries

As a programmer, you can never, and should never, write every single line of code that your code needs[1]. It turns out that you end up writing very little code for what your programs actually do. Lets start with a simple example. Every CS student learns how to implement a linked list, but how many times does a real life programmer actually write their own linked list implementation from scratch? Never! I’m not trying to debate whether or not CS students should have to learn how to implement a linked list, which BTW I think they should. My point is that all common programming languages provide libraries for common programming tasks, like linked lists, hash maps, sorting algorithms, math functions, and so on, so you don’t have to write them from scratch.

There are also more necessary uses of libraries that offer more than just saving time and effort. This is the case when you want to interact with any external component. GUI libraries are a good example. If you want to write software for the Android platform you must use their libraries in order to display things on the screen. There are hundreds, maybe thousands, of classes written by Google that provides access to the Android platform, primarily for creating and manipulating graphical widgets.

But how do you know how to use libraries? The typical approach to convey to you what a library does and how to use it is through API documentation and code examples. This helps most of the time, but sometimes it is a struggle to use libraries correctly. Sometimes you don’t know exactly what the API classes, methods, functions or whatever expect in and sometimes you don’t know exactly what will come out, even with what would be considered high quality documentation. Sometimes it is just complicated. Then there is poor quality documentation where it becomes a guessing game.

Where does API documentation and code examples come from? Code. Why then is code generally considered a non-traditional or even unacceptable method of learning how libraries work and how to use them in your code? First, many people are very protective of their code and don’t like to let other people see it. Maybe they think they have something special and don’t want anyone stealing their ideas. Maybe they are self-conscious about their work and are afraid of criticism or that other people will discover their poor coding abilities. Second, libraries are usually complicated and without an understanding of how the code is designed it can be difficult to make use it. It is also usually more time consuming to dig through and learn someone else’s code rather than reading their API documentation or examples. But sometimes it is worth it.

The first hurdle, actually getting people to let you read their source code, isn’t something I can appropriately address in this post. But I can say that this hurdle is a non-issue with FLOSS (free (as in libre) and open source software). It is for the very point of this post that I avoid non-free software libraries like the plague.

The second hurdle, the difficulty in reading library code, is usually easier to get around. Reading code is the most descriptive way to truly understand how a library works and how to use it. With a little time and practice, it’s really not that hard.

An interesting way I often use library code is for optimizations. As a simple example, let’s say you are using a sort method. Often times libraries will offer many ways of passing data into basically the same method. For a sort method, the library may accept either a List object or an array. If I pass in a List, does the library convert the List to an array, perform the sort on the array, then turn that array back into a list? If I can work with an array in my code just as easily as a list then I can skip the extra conversion by just working with an array. The information that says the List method has to convert to and from an array could be provided in other documentation, like Javadocs, but if it wasn’t then the only way to know is to look at the code to see what it does.

I often look at JDK library code. Sometimes it is for optimizations. Sometimes I can better understand its use if I look at the code. Sometimes it helps decide if I should extend a library class, extend one of its base classes, or something else. Sometimes I am just curious. But I know that I am more effective at coding and my code is better when I have access to library source code.

Reading other peoples code can also help you be a better programmer. You can discover new and better ways of doing things and you also get better at reading other peoples code which has benefits beyond reading library code.

So even though you may never write a linked list implementation, you may some day need to read the code of an implementation you are using and should know what it’s doing and why.

[1] This entire post is with exception of extremely uncommon situations, such as embedded systems or low-level system control.


Leave a Comment

NOTE - You can use these HTML tags and attributes:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>