

Clean Ruby - spooneybarger
http://www.clean-ruby.com/

======
rodw
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.

~~~
saturnflyer
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.

~~~
rodw
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>

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

~~~
saturnflyer
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.

~~~
mvzink
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.

~~~
saturnflyer
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.

------
igorgue
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.

~~~
sunnyprogram
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.

~~~
masklinn
> 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.

~~~
ollysb
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.

~~~
masklinn
> 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.

~~~
ollysb
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>

~~~
masklinn
> 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...](https://www.relishapp.com/myronmarston/vcr/docs/cassettes/cassette-
format)

------
akkartik
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...](http://en.wikipedia.org/wiki/Class-responsibility-
collaboration_card)

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

~~~
akkartik
I had only _heard_ of such clean perl. Thanks!

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

~~~
draegtun
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>

------
saturnflyer
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.

~~~
nwmcsween
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.

~~~
rjknight
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>

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

~~~
saturnflyer
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!

------
djacobs
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>

~~~
saturnflyer
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.

~~~
djacobs
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.

