Question

This is somewhat of a broad question, but it is one that I continue to come across when programming in Ruby. I am from a largely C and Java background, where when I use a library function or method, I look at the documentation and see what it returns on error (usually in C) or which exceptions it can throw (in Java).

In Ruby, the situation seems completely different. Just now I need to parse some JSON I receive from a server:

data = JSON.parse(response)

Naturally, the first thing I think after writing this code is, what if the input is bad? Is parse going to return nil on error, or raise some exception, and if so, which ones?

I check the documentation (http://flori.github.com/json/doc/JSON.html#M000022) and see, simply:

“Parse the JSON string source into a Ruby data structure and return it.”

This is just an example of a pattern I have run into repeatedly in Ruby. Originally, I figured it was some shortcoming of the documentation of whatever library I was working with, but now I am starting to feel this is standard practice and I am in a somewhat different mindset than Ruby programmers. Is there some convention I am unaware of?

How do developers deal with this?

(And yes I did look at the code of the library method, and can get some idea of what exceptions are raised but I cannot be 100% sure and if it is not documented I feel uncomfortable relying on it.)

EDIT: After looking at the first two answers, let me continue the JSON parsing example from above.

I suspect I should not do:

begin
  data = JSON.parse(response)
  raise "parse error" if data.nil?
rescue Exception => e
  # blahblah
end

because I can look at the code/tests and see it seems to raise a ParserError on error (returning nil seems to not be standard practice in Ruby). Would I be correct in saying the recommended practice is to do:

begin
  data = JSON.parse(response)
rescue JSON::ParserError => e
  # blahblah
end

…based upon what I learned about ParserError by looking through the code and tests?

(I also edited the example to clarify it is a response from a server that I am parsing.)

Answer 1

(And yes I did look at the code of the library method, and can get some idea of what exceptions are raised but I cannot be 100% sure and if it is not documented I feel uncomfortable relying on it.)

I suggest having a look at the tests, as they will show some of the “likely” scenarios and what might be raised. Don’t forget that good tests are documentation, too.