Clean Ruby | Hacker News Reader

Clean Ruby

clean-ruby.com

63 pointsspooneybarger33 comments

Just so you know, the content of that page is frustratingly slightly too wide to display on my 1024-pixel-wide netbook screen. (Using Chromium/Chrome on Linux, with Helvetica, it comes out to 1009 pixels.)

This means (a) I have horizontal scroll bar added to my browser window, (b) I need to scroll a bit left/right to read some of the text, (c) it is easy to accidentally "wobble" the horizontal scroll bar when trying to scroll vertically using multi-touch gestures.

If you were to shrink the width just slightly your site would be much more comfortable to read at 1024 pixels wide. As it stands I won't read the long-form letter because of the annoyances above. The bits I read sound interesting.

for you rodw, I shortened the width. It should be 970px now.

It's just been one of those things: wait to get it perfect or get it done. It's probably not great on a mobile phone either but I haven't had time to tackle that.

I sympathize. It can be hard to cover all the browser/platform options.

I'm still getting the scroll bar. There may be other reasons as well, but it looks like your header image[1] is 1016 pixels wide. I tried reloading without cache, but it is possible I'm getting an old version somehow.

I'm not sure how wide the scrollbar/window chrome typically are but I think I'd allow a 20 pixel buffer at minimum (i.e. 996 width). Personally, I'd probably allow a 40+ pixel buffer just to be safe, but I in practice I just use the 960px width that 960.gs and others popularized. 64 pixels might be a little generous, but it does allow the page a little breathing room even on 1024 monitors.

1024 might be becoming a rare screen size (I don't know either way), but the vast majority of the sites I visit work at 1024 without horizontal scrolling. (A bigger problem for me is the 600px height. Even at full screen the modal popups some websites use are off-screen. I know how to scale and/or drag the window to work around that, but I'm sure most users don't.)

[1] http://s3.amazonaws.com/solarhost/21/assets/57/header.png

I went to the site, read several things, and still have no idea what you want me to sign up for.

Thanks for the feedback. I'll clean up the text a bit then. Subscribers will get a discount on "Clean Ruby" when it's finished.

It would be more obvious that this was a listhost and not a "sign up" (per se; you get my meaning) if there was only one text input. Even have the name appear after clicking on the first input.

Well, I'm not sure I do know what you mean. If you fill out the form, I'll email you with updates and eventually a discount code.

This is one of the reasons why I like Python more than Ruby, the emphasis on not writing documentation, guys, get over it, you always need documentation, self-documented code is a huge lie.

What's next? Tests are a waste of time?

P.S.: Not all Ruby programmers are like that obviously that's why this exists http://tomdoc.org/ Zack thinks the same way http://twitter.com/#!/holman/status/144579142367711234 And there's a good movement of Ruby hackers that think that way.

This book isn't an argument against documentation. Until the recent advent of DCI there was no programming paradigm that brought the algorithm to be a first class citizen. Tomdoc looks great, but it only describes methods or classes. Documentation will not tell you what will happen among a network objects during runtime, DCI will.

Got it.

"While following the Model View Controller approach has made your code cleaner, and following conventions have reduced the need for documentation, there’s still plenty of room for improvement and too much time needed to instruct new developers."

That made me think that the goal was writing less documentation.

Interesting. Maybe I'll rewrite that bit. Thanks for pointing that out.

Most if not all projects in use written in ruby use rdoc, rocco or some form of inline documentation. I would be very surprised if a well used gem didn't have documentation.

WEBrick?

I disagree. If you follow test driven development, your tests become your documentation. Want to know what a method does? Look at the tests for the method where it explicitly says what the method is doing and ensures it is functioning correctly.

> If you follow test driven development, your tests become your documentation.

That's the shittiest documentation in existence.

Your tests are implementation documentation, they're useful (maybe) for other maintainers, and useless for third-parties trying to actually use your code.

> Want to know what a method does? Look at the tests for the method where it explicitly says what the method is doing and ensures it is functioning correctly.

Right, look at 700 lines of edge cases testing, that's informative and helpful. Not.

That's the difference between TDD and BDD, if you're practicing BDD then your tests will be documenting how to use your code, not how it's implementation works.

> if you're practicing BDD then your tests will be documenting how to use your code

I'm going to call bullshit on that one all the same.

This site builds docs for projects based on their integration tests. I think it's a pretty good example of what you can achieve using BDD for documentation, https://www.relishapp.com/myronmarston/vcr

> I think it's a pretty good example of what you can achieve using BDD for documentation

And as expected, it's awful.

The front page looks good. It's also a Markdown document. Open any actual feature dump[0] and you land straight in dreadful-land. The introduction is acceptably readable (since it's written in markdown throughout), the "code samples" are mostly an unreadable mess with little logical flows and huge blocks of unreadable code. It manages to fail both at being a documentation and at being an APIdoc.

The most laughable part is the "Examples" sections as they show not examples but values with which the placeholders in the rspec test can be replaced.

The only part worth reading of these is the heading, which has nothing to do with RSpec, and the only thing rspec doee is makes this "documentation" worse by imposing the test's structure onto the documentation.

It's not even a step up form having only extracted APIDoc, it's a step down.

[0] https://www.relishapp.com/myronmarston/vcr/docs/cassettes/ca...

I hope you don't ever write a library that I would want to use.

Useful background: http://en.wikipedia.org/wiki/Data,_Context,_and_Interaction

http://www.artima.com/articles/dci_vision.html

It also reminds me of http://en.wikipedia.org/wiki/Class-responsibility-collaborat...

Thus far I've found this the easiest article to grok DCI: https://metacpan.org/module/DCI

I had only heard of such clean perl. Thanks!

From these examples DCI seems a lot like lisp's generic functions..

re: clean perl and generic functions - have a look at Moose. Its Perl's equivalent of CLOS.

* http://moose.perl.org

* https://metacpan.org/module/Moose

* https://metacpan.org/module/Class::MOP

* BankAccount example (Practical Common Lisp) - https://metacpan.org/module/Moose::Cookbook::Basics::Recipe2

Clean Ruby is all about writing applications that are easy to understand by elevating the use case to a first class citizen. OO programs often split out methods and objects required for a use case like shrapnel. After reading Clean Ruby, you'll know how to bring them all together in one place to reveal your intent.

Ok so you're the author but this statement is pretty cryptic can you expand up on how DCI would make things better than the tried and tested test -> programming -> factoring out path most programmers take? Even rails takes this model.

DCI doesn't necessarily mean fewer tests - done correctly it can make testing easier since it can help to separate concerns and allow for easy testing of discrete components. I don't think this is the killer feature for DCI though; you can do this with other OO methodologies just as well.

DCI's main advantage is that it encourages you to write code that follows an "assemble the objects I need, then perform a sequence of operations on them" pattern, where the operations generally occur inside a single method. This is your algorithm, and the idea is that you should be able to read that algorithm and get a good idea of what the program is doing. Instead of relying on tests alone to verify that your program does what it's meant to, you should be able to read the code too.

Jim Coplien's talk here is a good intro: http://www.infoq.com/presentations/The-DCI-Architecture

DCI has you split objects from their responsibilities until they are needed. This reduces your need to understad what eventually becomes (commonly in projects) massive classes with lots of responsibilities. But more so than that, in DCI you create a Context object whose responsibility is to coordinate objects and the roles they play: the Context represents your algorithm. This allows you to point to an object that is responsible for a business use case, rather than what is typically done by having methods strewn about the classes of you system with no indication of when they are needed.

it only says "book" once before the signup form - and it's small text at the bottom of the page.

I've updated the text a bit and changed the signup button at the top to be a bit more obvious about it being a book. Thanks for the feedback!

When Rich Hickey talks about code simplicity, he is referring to things that Ruby (simply) cannot simplify.

http://www.infoq.com/presentations/Simple-Made-Easy

I took that quote from that presentation. He hates all OO code, so it's not specifically Ruby that's the problem for him, but object orientation. His point, however, is that being able to reason about your program is important. That is also a driving factor behind DCI. OO programs often hide exactly what happens among objects because we mostly see everything from the perspective of a class, rather than a perspective of being among the communicating objects.

I'm not sure that he broadly hates object-orientation as an idea. It's true, he hates much of the conflation that goes in OO (E.g., conflating classes with namespaces, objects with data structures, encapsulation with object ownership, and identity with state). And he hates the reliance on tests to overcome that conflation and confusion--something that's hugely prevalent in the Ruby world. But he does allow most of the features of OO in Clojure.

Reply on news.ycombinator.com