6 ms·

Ruby Best Practices (full book available for download)

151 points by figured 17y ago

Pistos2 17y ago
Thank you for writing this, and thanks for open sourcing it.
- sandal 17y ago
  The Ruby community has taught me so much, it seems the reasonable thing to do. Also, old books tend to go out of print, and then die sad, lonely out-of-date deaths. Maybe this will keep RBP moving forward, and keep it alive.
sandal 17y ago
For the tl;dr crowd, this will take you straight to the PDF: http://sandal.github.com/rbp-book/pdfs/rbp_1-0.pdf http://sandal.github.com/rbp-book/pdfs/rbp_1-0.pdf (But please read the article, it provides context :)
- ddemchuk 17y ago
  you provided a tl;dr link to a BOOK???! haha, wednesday morning irony ftw
  - sandal 17y ago
    Hah, the irony here did not escape me. But good point. So... here's the tl;dr; for the book itself: "Ruby provides many ways to do things, many of them decent. But some are usually better than others, depending on the context."
onewland 17y ago
This looks sweet. Thanks sandal (for writing)/figured (for posting).
bgraves 17y ago
So, is this the full version of the O'Reilly book [1] or something different? I'm curious about the business end of this project: did you sell this PDF before giving it away for free? How much revenue have you brought in? How much time have you spent writing/compiling/editing this book in it's current state. It seems like a very highly regarded book (judging from the Amazon reviews) so perhaps I am just out of the loop on this one, but I find the business aspect of these ventures most interesting. [1]http://www.amazon.com/s?ie=UTF8&tag=mozilla-20&index=blended&link_code=qs&field-keywords=Ruby%20Best%20Practices&sourceid=Mozilla-search http://www.amazon.com/s?ie=UTF8&tag=mozilla-20&index...
- sandal 17y ago
  It is exactly what was used to generate the print book, just with some web enabled features like links. And yes, this is the PDF you'd get if you buy it from O'Reilly. Marketing-wise, it was a gamble, because the open source release date wasn't contingent on sales or anything like that. We launched the book and gave a 9 month exclusive rights period to O'Reilly. This at least takes into account the fact that most books sell the majority of their copies in the first month or two, but I didn't have like a minimum sales number before I could open source the book or anything like that. In fact, the print book says right in the front cover that it'd be open sourced in March. The book did okay sales wise, not great, but not horrible. It definitely did worse than it should given that (at least from the looks of it) people really, really like it. But this isn't really up to the readers, it's up to the distributor. Basically, much of our sales come from wholesale, and with paper book stores on the decline, and the saturation of the market with Ruby books over the last couple years, it was hard to convince them to pick up a lot of copies of the book. As of right now, I am just about at the point of clearing my advance. I will share specific numbers at some point, but let's just say that the advance probably works out to minimum wage or less when compared to the amount of effort put in. Interestingly enough, the gradual week by week release of chapters really led to a nice spike in sales, coming from what was essentially a steady decline except for a spike around the holidays. So actually, I think open sourcing the book was good for sales in that regard. Since it might be hard to find the book on the shelves in a book store, this gives people a chance to "try before they buy". Unfortunately, because my book was selling above average as an ebook, I've probably effectively killed those sales today. Then again, maybe people will still buy the Kindle and Iphone editions, who knows. At the end of the day, I think neither O'Reilly nor myself expected this book to be a big bread winner. I love the book because it embodies the most interesting things I've learned from the smartest people I know, and I think that comes through in the writing. I wrote the book because the idea popped into my head fully formed and demanded to be put out on paper. So that was my biggest win. But from an authors perspective, RBP has given me a great boost in exposure. I already had name recognition in the inner circles of Ruby community, but after writing the book, I find more opportunities from folks I probably wouldn't have been able to reach otherwise. This has been good for my open source projects, and good for my work. I'm glad I did this, and it worked out well. I'd recommend it to others, for sure. Of course, buying the book will make O'Reilly happy, so go ahead and do that if you want :)
figured 17y ago
I recommend this book whole heartily. I have been reading the chapters as they have been released, an excellent resource.
jamesbritt 17y ago
Sweet! Thanks, Greg.
richcollins 17y ago
Keyword arguments via hashes is certainly not a best practice for "Beautiful API Design". Sending messages is part and parcel to good OO design. Code that deconstructs hashes to emulate keyword arguments is invariably hideously complicated.
- lg 17y ago
  Would you prefer a *rest argument? An options hash is the best way to make your ruby API flexible.
  - richcollins 17y ago
    Plain old objects are the best way to make your API design flexible. You can't easily change the behavior of setting a key/value pair for an individual hash. Objects are designed to implement behavior, Hashs are meant to hold key value pairs.
    - kogent 17y ago
      The book is opensource, why not submit a <strike>patch</strike> pull request. :)
      - sandal 17y ago
        In all seriousness, all it takes is some code examples that make me and a few others say "whoa, cool" and it'll make its way in. If RBP becomes "Gregory Brown's Best Practices", it'll be epic fail. I am encouraging folks to prove whatever they can wrong in this book.
    - deleted 17y ago
      [deleted]
    - lg 17y ago
      Right, the keys/values need to have supporting logic. And yeah if you're sticking procs in a hash, just use an object; but if your object is just a bunch of fields, use a hash. And often that's all you need. I just want to override the marginWidth on this fooBar. Remember you don't need to destructure the hash. You've got a local one initialized to sensible defaults, and you .merge! it with the param one, and then just use the hash values as your local vars.
daveungerer 17y ago
The sandal username on GitHub sounded familiar, so I checked and realised its the same sandal that does the Prawn PDF library: http://github.com/sandal/prawn http://github.com/sandal/prawn That gives the book some extra credibility in my eyes. EDIT: OK, now that I've read the foreward, I see Matz himself mentions Gregory's work on Prawn. Doh.
- sandal 17y ago
  Yes, I started Prawn via the "Ruby Mendicant" project: http://majesticseacreature.com/mendicant/ http://majesticseacreature.com/mendicant/ I'm still active in the project as a maintainer. But really, these days you have Brad Ediger, James Healy, and Daniel Nelson, along with about 60+ contributors to thank for where Prawn is heading. My job is mostly to sit around naming things, and warning people about the fragility of the early code I wrote. But we will have a 1.0 plan soon, and no matter who does the work, that'll be good for everybody.
therealist 17y ago
http://fraudit.wordpress.com/ http://fraudit.wordpress.com/
erikpukinskis 17y ago
Here's a copy on Google Docs. I hate PDFs: https://docs.google.com/fileview?id=0B8mB_WI1jRkCMzgyZWY5MzYtOTM0NC00YTRiLTg3NWMtZDU1MTdmM2QzNzU0&hl=en https://docs.google.com/fileview?id=0B8mB_WI1jRkCMzgyZWY5MzY...
- sandal 17y ago
  I'll run the book through asciidoc's html generator soon enough, but thanks for doing this for now. Looks like it loses some quality on translation to Google docs, though...
sandal 17y ago
BTW, going to experiment with using a wiki page for collecting reader questions. Once I have a few lined up, I'll cut a blog post reply on the RBP blog. http://wiki.github.com/sandal/rbp-book/questions-for-gregory http://wiki.github.com/sandal/rbp-book/questions-for-gregory

151 points by figured 17y ago

Pistos2 17y ago

Thank you for writing this, and thanks for open sourcing it.

sandal 17y ago
The Ruby community has taught me so much, it seems the reasonable thing to do. Also, old books tend to go out of print, and then die sad, lonely out-of-date deaths. Maybe this will keep RBP moving forward, and keep it alive.

sandal 17y ago

For the tl;dr crowd, this will take you straight to the PDF: http://sandal.github.com/rbp-book/pdfs/rbp_1-0.pdf http://sandal.github.com/rbp-book/pdfs/rbp_1-0.pdf (But please read the article, it provides context :)

ddemchuk 17y ago
you provided a tl;dr link to a BOOK???! haha, wednesday morning irony ftw
- sandal 17y ago
  Hah, the irony here did not escape me. But good point. So... here's the tl;dr; for the book itself: "Ruby provides many ways to do things, many of them decent. But some are usually better than others, depending on the context."

onewland 17y ago

This looks sweet. Thanks sandal (for writing)/figured (for posting).

bgraves 17y ago

So, is this the full version of the O'Reilly book [1] or something different? I'm curious about the business end of this project: did you sell this PDF before giving it away for free? How much revenue have you brought in? How much time have you spent writing/compiling/editing this book in it's current state. It seems like a very highly regarded book (judging from the Amazon reviews) so perhaps I am just out of the loop on this one, but I find the business aspect of these ventures most interesting. [1]http://www.amazon.com/s?ie=UTF8&tag=mozilla-20&index=blended&link_code=qs&field-keywords=Ruby%20Best%20Practices&sourceid=Mozilla-search http://www.amazon.com/s?ie=UTF8&tag=mozilla-20&index...

sandal 17y ago
It is exactly what was used to generate the print book, just with some web enabled features like links. And yes, this is the PDF you'd get if you buy it from O'Reilly. Marketing-wise, it was a gamble, because the open source release date wasn't contingent on sales or anything like that. We launched the book and gave a 9 month exclusive rights period to O'Reilly. This at least takes into account the fact that most books sell the majority of their copies in the first month or two, but I didn't have like a minimum sales number before I could open source the book or anything like that. In fact, the print book says right in the front cover that it'd be open sourced in March. The book did okay sales wise, not great, but not horrible. It definitely did worse than it should given that (at least from the looks of it) people really, really like it. But this isn't really up to the readers, it's up to the distributor. Basically, much of our sales come from wholesale, and with paper book stores on the decline, and the saturation of the market with Ruby books over the last couple years, it was hard to convince them to pick up a lot of copies of the book. As of right now, I am just about at the point of clearing my advance. I will share specific numbers at some point, but let's just say that the advance probably works out to minimum wage or less when compared to the amount of effort put in. Interestingly enough, the gradual week by week release of chapters really led to a nice spike in sales, coming from what was essentially a steady decline except for a spike around the holidays. So actually, I think open sourcing the book was good for sales in that regard. Since it might be hard to find the book on the shelves in a book store, this gives people a chance to "try before they buy". Unfortunately, because my book was selling above average as an ebook, I've probably effectively killed those sales today. Then again, maybe people will still buy the Kindle and Iphone editions, who knows. At the end of the day, I think neither O'Reilly nor myself expected this book to be a big bread winner. I love the book because it embodies the most interesting things I've learned from the smartest people I know, and I think that comes through in the writing. I wrote the book because the idea popped into my head fully formed and demanded to be put out on paper. So that was my biggest win. But from an authors perspective, RBP has given me a great boost in exposure. I already had name recognition in the inner circles of Ruby community, but after writing the book, I find more opportunities from folks I probably wouldn't have been able to reach otherwise. This has been good for my open source projects, and good for my work. I'm glad I did this, and it worked out well. I'd recommend it to others, for sure. Of course, buying the book will make O'Reilly happy, so go ahead and do that if you want :)

figured 17y ago

I recommend this book whole heartily. I have been reading the chapters as they have been released, an excellent resource.

jamesbritt 17y ago

Sweet! Thanks, Greg.

richcollins 17y ago

Keyword arguments via hashes is certainly not a best practice for "Beautiful API Design". Sending messages is part and parcel to good OO design. Code that deconstructs hashes to emulate keyword arguments is invariably hideously complicated.

lg 17y ago
Would you prefer a *rest argument? An options hash is the best way to make your ruby API flexible.
- richcollins 17y ago
  Plain old objects are the best way to make your API design flexible. You can't easily change the behavior of setting a key/value pair for an individual hash. Objects are designed to implement behavior, Hashs are meant to hold key value pairs.
  - kogent 17y ago
    The book is opensource, why not submit a <strike>patch</strike> pull request. :)
    - sandal 17y ago
      In all seriousness, all it takes is some code examples that make me and a few others say "whoa, cool" and it'll make its way in. If RBP becomes "Gregory Brown's Best Practices", it'll be epic fail. I am encouraging folks to prove whatever they can wrong in this book.
  - deleted 17y ago
    [deleted]
  - lg 17y ago
    Right, the keys/values need to have supporting logic. And yeah if you're sticking procs in a hash, just use an object; but if your object is just a bunch of fields, use a hash. And often that's all you need. I just want to override the marginWidth on this fooBar. Remember you don't need to destructure the hash. You've got a local one initialized to sensible defaults, and you .merge! it with the param one, and then just use the hash values as your local vars.

daveungerer 17y ago

The sandal username on GitHub sounded familiar, so I checked and realised its the same sandal that does the Prawn PDF library: http://github.com/sandal/prawn http://github.com/sandal/prawn That gives the book some extra credibility in my eyes. EDIT: OK, now that I've read the foreward, I see Matz himself mentions Gregory's work on Prawn. Doh.

sandal 17y ago
Yes, I started Prawn via the "Ruby Mendicant" project: http://majesticseacreature.com/mendicant/ http://majesticseacreature.com/mendicant/ I'm still active in the project as a maintainer. But really, these days you have Brad Ediger, James Healy, and Daniel Nelson, along with about 60+ contributors to thank for where Prawn is heading. My job is mostly to sit around naming things, and warning people about the fragility of the early code I wrote. But we will have a 1.0 plan soon, and no matter who does the work, that'll be good for everybody.

therealist 17y ago

http://fraudit.wordpress.com/ http://fraudit.wordpress.com/

erikpukinskis 17y ago

Here's a copy on Google Docs. I hate PDFs: https://docs.google.com/fileview?id=0B8mB_WI1jRkCMzgyZWY5MzYtOTM0NC00YTRiLTg3NWMtZDU1MTdmM2QzNzU0&hl=en https://docs.google.com/fileview?id=0B8mB_WI1jRkCMzgyZWY5MzY...

sandal 17y ago
I'll run the book through asciidoc's html generator soon enough, but thanks for doing this for now. Looks like it loses some quality on translation to Google docs, though...

sandal 17y ago

BTW, going to experiment with using a wiki page for collecting reader questions. Once I have a few lined up, I'll cut a blog post reply on the RBP blog. http://wiki.github.com/sandal/rbp-book/questions-for-gregory http://wiki.github.com/sandal/rbp-book/questions-for-gregory