Comments:"RTFC is the New RTFM* | Jake Radakovich's Code Review"
URL:http://jakeradakovich.wordpress.com/2013/04/24/rtfc-is-the-new-rtfm/
Lately, I seem to be reading a lot of source code. The source code that I’m reading is not my own, and it’s not even code that I am actively creating or maintaining. The code that I am reading is in open source libraries, and I’m reading it to figure out how to use them.
The bane of my existence these days has been securing my company’s large, legacy web application’s new web services using a popular OAuth library. Part of the problem is the “standard,” but part of it is also the available libraries.
The documentation for the library we chose is sparse. There is prodigious use of convention over configuration. Many would consider this a good thing, and, heck, I would consider this a good thing if I could easily find and decipher the convention. Convention over configuration loses its value when nobody knows the convention.
A couple of days ago, a good friend and I were trying to implement the aforementioned OAuth solution. We couldn’t figure out the convention, and we were stuck. I nonchalantly told him to look at the source code of the library we were using. He looked at me like I had asked him to help me dig up a grave, but he relented. We attached the source files, stepped through the source, and figured out what we were doing wrong.
One of the many benefits of open source software is the ability to see the source code. There is no better way to know how a library works than to look at the code. The documentation for many open source libraries is pretty sparse, so sometimes it’s necessary to look at the code. Not only can it help solve immediate problems, but it also makes you a better developer by exposing you to other developers’ code and style.
I realize complaining about the lack of documentation in some open source projects is like complaining that there is no foie gras at a friend’s free dinner party, but that’s another beauty of open source software – we can contribute to the documentation. Contributing to documentation is definitely not the most glamorous way to support open source software, but it is a great way to help the community and potential users.
The Spring Security documentation says it best…
It is much easier to debug your application or to work out where a problem lies if you don’t treat the external code you are working with as a black box which you never look inside. The first thing you should do when an exception you don’t understand is thrown from an open source library is jump to the class and line number and take a look to figure out what the code was doing there. Otherwise you’re missing out on much of the benefit of using open source code.Don’t be scared to take a peek at the source code. It will save you a lot of time and headache. I’d love to hear your thoughts in the comments below.
*Read the F$%&ing Code is the New Read the F$%&ing Manual
Tagged:open source, spring security