Command-query separation and explicit vs. implicit return in Ruby

ruby-talk
1

Hi,

I’ve been wondering for some time about how to best handle command-query separation (CQS) and explicit vs. implicit returns in Ruby.

Following CQS there are methods which change something (commands) and methods which return something (queries) and ideally you don't mix them up.

Command methods should return „nothing“ from my point of view but in Ruby the preferred way seems to be the implicit return, which leads to command methods returning some more or less random value depending on the last statement / expression of the method.

I have seen some command methods with an explicit return without a value (=>nil) but as this get’s a Rubocop warning by default it doesn’t seem to be the "Ruby way". I’ve seen command methods returning "self" - which I can't get my head around - and sometimes returning "" to explicitly return "nothing". But at least from the code I’ve seen so far it seems to me, the preferred way being the implicit return, hence more or less „violating“ CQS.

Are there any best practices? And what's the idea of returning self?

Many thanks for any hints on this!

Cheers,
Michael

2

You will usually return self if you're developing an api that benefits from
method chaining.

Rubocop will complain if you use the return keyword explicitly. If you
just want a method to return nil, just write nil as the last expression,
without the return keyword.

Personally, I pay no to little attention to the return value of command
methods. As long as the method signature makes it clear to be a command
method, I think it is up to the caller to not rely on the return value
since by definition it is irrelevant. Given that, an empty string, nil,
the number 42 or the result of the last expression, whatever it is, are
all good candidates. But that's just my opinion.

Cheers

···

Em dom, 25 de set de 2016 18:27, Michael Schwarze <michael@schwarze-web.de> escreveu:

Hi,

I’ve been wondering for some time about how to best handle command-query
separation (CQS) and explicit vs. implicit returns in Ruby.

Following CQS there are methods which change something (commands) and
methods which return something (queries) and ideally you don't mix them up.

Command methods should return „nothing“ from my point of view but in Ruby
the preferred way seems to be the implicit return, which leads to command
methods returning some more or less random value depending on the last
statement / expression of the method.

I have seen some command methods with an explicit return without a value
(=>nil) but as this get’s a Rubocop warning by default it doesn’t seem to
be the "Ruby way". I’ve seen command methods returning "self" - which I
can't get my head around - and sometimes returning "" to explicitly return
"nothing". But at least from the code I’ve seen so far it seems to me, the
preferred way being the implicit return, hence more or less „violating“ CQS.

Are there any best practices? And what's the idea of returning self?

Many thanks for any hints on this!

Cheers,
Michael

Unsubscribe: <mailto:ruby-talk-request@ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-talk&gt;

3

Command methods should return „nothing“ from my point of view but in Ruby the preferred way seems to be the implicit return, which leads to command methods returning some more or less random value depending on the last statement / expression of the method.

For public methods I usually make sure no internal data is leaked
because this would allow accidental or intentional manipulation of
instance state which likely violates the class invariant.

I have seen some command methods with an explicit return without a value (=>nil) but as this get’s a Rubocop warning by default it doesn’t seem to be the "Ruby way". I’ve seen command methods returning "self" - which I can't get my head around - and sometimes returning "" to explicitly return "nothing". But at least from the code I’ve seen so far it seems to me, the preferred way being the implicit return, hence more or less „violating“ CQS.

Returning nil instead of an empty String seems so much more
reasonable. Where did you see the empty String return?

Are there any best practices? And what's the idea of returning self?

For Enumerable#each and similar methods it is conventional. It will
allow chaining if that is necessary but I have rarely seen that.

Having said all that, the focus in Ruby is generally on pragmatic
reasonable solutions and less on strictly adhering some kind of rule
system. I cannot recall a discussion about this very topic here (but
then again, my memory might have suffered over the years) so it might
not be considered too important by Rubyists. I do like these
discussions as they often reveal interesting insights or even provide
a learning experience. We have these rarely these days - sadly.

Kind regards

robert

···

On Sun, Sep 25, 2016 at 6:21 PM, Michael Schwarze <michael@schwarze-web.de> wrote:

--
[guy, jim, charlie].each {|him| remember.him do |as, often| as.you_can
- without end}
http://blog.rubybestpractices.com/

4

Returning `self' allows you to chain method calls. This is for example
fairly nice with operators; Array#<< for example returns `self' so you can
do things like this:

    ary =
    ary << "foo" << 3
    p ary #=> ["foo", 3]

In a custom class, this can be achieved like this:

    class Foo

      attr_reader :store

      def initialize
        @store =
      end

      def <<(arg)
        @store << arg
        self
      end

    end

    f = Foo.new
    f << "foo" << 3
    p f.store

Note how Foo#<< returns `self'. If you have it return `nil' or anything
not responding to `<<', then the second-to-last line of this example
will fail with a NoMethodError exception.

Greetings
Marvin

···

On Sun, Sep 25, 2016 at 06:21:22PM +0200, Michael Schwarze wrote:

Are there any best practices? And what's the idea of returning self?

--
Blog: http://www.guelkerdev.de
PGP/GPG ID: F1D8799FBCC8BC4F

5

Hi,

Many thanks for the great feedback and for taking your time! I’ll try to wrap-up the main points of the discussion first:

As everything’s an expression in Ruby, the last statement of a method defines its return value; the favored implicit return. Alternatively, you can explicitly return with the return statement, which is not the common way in Ruby. This leaves it open how to return from a command-method (CQS[1]), which should ideally return nil. A majority, at least in this discussion, sticks to the implicit return even in command-methods, leaving it up to the caller to ignore the more or less random return value. This bears the risk of leakage of internal data and other unintended consequences (dependencies, …). One suggestion, wich is like, is to explicitly return (nil) from public command-methods. Returning self is another topic, related to chaining methods.

The summary and my understanding is based on the following extract / details from the discussion:

···

Am 25.09.2016 um 18:43 schrieb Samuel Brandão <gb.samuel@gmail.com>:

If you just want a method to return nil, just write nil as the last expression, without the return keyword.

Am 25.09.2016 um 19:08 schrieb Robert Klemme <shortcutter@googlemail.com>:

Returning nil instead of an empty String seems so much more reasonable

Good point(s)! So,

~~~
def foo_cmd
   # …
   nil
end
~~~

is kind of the „explicit-implicit“ return for command methods; from my point of view this makes the command nature of a method very clear / explicit.

Am 25.09.2016 um 19:08 schrieb Robert Klemme <shortcutter@googlemail.com>:

Where did you see the empty String return?

Thanks for pointing me in that direction; I looked it up again and have to correct myself: it was a query method yielding strings (as enums) and returning the empty string as the last one to indicate the end of the enum.

Am 25.09.2016 um 18:43 schrieb Samuel Brandão <gb.samuel@gmail.com>:

it is up to the caller to not rely on the return value

Which seems to be consensus:

Am 25.09.2016 um 21:30 schrieb Marvin Gülker <m-guelker@phoenixmail.de>:

I do think that the community does not really care

I think of being explicit about the nature of a method at least as kind of a courtesy to the caller / other programmers. Therefore, I like Robert’s approach of at least being explicit in public methods as a reasonable tradeoff, esp. as there’s obviously more to it than courtesy:

Am 25.09.2016 um 19:08 schrieb Robert Klemme <shortcutter@googlemail.com>:

For public methods I usually make sure no internal data is leaked because this would allow accidental or intentional manipulation of instance state which likely violates the class invariant.

The risk is that someone might tie herself to this undocumented and implicit part of the public API of a class.

Am 25.09.2016 um 19:08 schrieb Robert Klemme <shortcutter@googlemail.com>:

the focus in Ruby is generally on pragmatic reasonable solutions and less on strictly adhering some kind of rule system

I totally agree and wouldn’t like Ruby as much as I do if it were differently! My intention was to get a feeling of how other developers handle this much appreciated "freedom" offered by the language.

Am 25.09.2016 um 21:11 schrieb Marvin Gülker <m-guelker@phoenixmail.de>:

Returning `self' allows you to chain method calls. This is for example fairly nice with operators; […]

Many thanks for your really helpful example; I’ll have to play around with it a little bit but I think I’ve got the point of returning self now. It is not meant as a replacement for nil for command methods, but THE return value of this kind of (query) methods.

Am 25.09.2016 um 21:30 schrieb Marvin Gülker <m-guelker@phoenixmail.de>:

if a method has no documented return value, it is a „command method“

Hm, I’m not sure I like that one…relying on documentation? I can see your point here, but documentation is neither a „first-class citizen“ of any programming language I know of, nor of most of the developers I’m aware of, including me, so it boils down to luck, which is never a good principle. Which kind of documentation do you have in mind here?

Am 25.09.2016 um 21:30 schrieb Marvin Gülker <m-guelker@phoenixmail.de>:

I would welcome more discussions like these as well as they have become way too rare

Good to know; I was not sure whether to start this discussion here or not as it definitely is a slightly more general topic.

So again, a big thanks to the contributors; your input and time is really appreciated and not taken for granted!

Cheers,
Michael

[1] Command Query Separation

6

> I have seen some command methods with an explicit return without a
> value (=>nil) but [...] it doesn’t seem to be the "Ruby way". I’ve
> seen command methods returning "self" [...] and sometimes returning
> "" to explicitly return "nothing".

Returning nil instead of an empty String seems so much more
reasonable.

I agree that returning the empty string looks very strange. It is just
some random value. If you really want to return something unreasonable,
you should at least have humour and return the number 42.

Having said all that, the focus in Ruby is generally on pragmatic
reasonable solutions and less on strictly adhering some kind of rule
system.

I have not yet seen methods marked explicitely as command methods or
otherwise in Ruby, and I do think that the community does not really
care. What is much more important is how the method is documented. If a
method has a documented return value, then you can rely on it. If a
method does not have a documented return value, do not rely on it. Or to
come back to the OP's terminology: if a method has no documented return
value, it is a "command method". It is a facet of the Ruby language that
each and every method returns something; there is no `void' "type" in
Ruby as in some compiled languages. It allows all methods to be treated
alike and simplifies the structure of the language. However, if it is
not documented (or you are the author of the method and _know_ it) then
the return value is of no use anyway as it could be anything and change
in new versions.

When writing Ruby code for methods that do not explicitely return
something of use, most people to my experience indeed "rely" on the
implicit return Ruby offers, except that I would not call it "relying"
on it, but simply "ignoring" the method's return value. Occasionally I
have seen methods that have no intended return value to explicitely
return `nil', but these are rather rare occurences. I would not go as
far and call it unidiomatic, but it surely shows the author is of a
pedantic nature.

It is different when you write a C extension for Ruby, because there is
no implicit return and even in a method that does not return anything
meaningful, you need to explicitely return something, because otherwise
the compiler is going to yell at you. In these cases, one usually
returns mrb_nil_value() which translates to `nil' on the Ruby side. As a
result, gems with C extensions will usually have more methods with an
explicit return value of `nil' than gems written in pure Ruby.

I cannot recall a discussion about this very topic here (but
then again, my memory might have suffered over the years) so it might
not be considered too important by Rubyists. I do like these
discussions as they often reveal interesting insights or even provide
a learning experience. We have these rarely these days - sadly.

I would welcome more discussions like these as well as they have become
way too rare. But one can't enforce this. Seufz.

Greetings
Marvin

···

On Sun, Sep 25, 2016 at 07:08:10PM +0200, Robert Klemme wrote:

--
Blog: http://www.guelkerdev.de
PGP/GPG ID: F1D8799FBCC8BC4F

7

Another option is to create a special class just to make it clear that the
method returns nothing. i.e. class Nothing;end;

And have a globally accesible method that returns instances of that special
class.

def foo_cmd
    # do whatever you need....
    nothing
end

I been using this a couple of times, but I'm not sure if this is the ruby
way.

···

On 26 September 2016 at 17:32, Michael Schwarze <michael@schwarze-web.de> wrote:

Hi,

Many thanks for the great feedback and for taking your time! I’ll try to
wrap-up the main points of the discussion first:

As everything’s an expression in Ruby, the last statement of a method
defines its return value; the favored implicit return. Alternatively, you
can explicitly return with the return statement, which is not the common
way in Ruby. This leaves it open how to return from a command-method
(CQS[1]), which should ideally return nil. A majority, at least in this
discussion, sticks to the implicit return even in command-methods, leaving
it up to the caller to ignore the more or less random return value. This
bears the risk of leakage of internal data and other unintended
consequences (dependencies, …). One suggestion, wich is like, is to
explicitly return (nil) from public command-methods. Returning self is
another topic, related to chaining methods.

The summary and my understanding is based on the following extract /
details from the discussion:

> Am 25.09.2016 um 18:43 schrieb Samuel Brandão <gb.samuel@gmail.com>:
>
> If you just want a method to return nil, just write nil as the last
expression, without the return keyword.

> Am 25.09.2016 um 19:08 schrieb Robert Klemme <shortcutter@googlemail.com > >:
>
> Returning nil instead of an empty String seems so much more reasonable

Good point(s)! So,

~~~
def foo_cmd
   # …
   nil
end
~~~

is kind of the „explicit-implicit“ return for command methods; from my
point of view this makes the command nature of a method very clear /
explicit.

> Am 25.09.2016 um 19:08 schrieb Robert Klemme <shortcutter@googlemail.com > >:
>
> Where did you see the empty String return?

Thanks for pointing me in that direction; I looked it up again and have to
correct myself: it was a query method yielding strings (as enums) and
returning the empty string as the last one to indicate the end of the enum.

> Am 25.09.2016 um 18:43 schrieb Samuel Brandão <gb.samuel@gmail.com>:
>
> it is up to the caller to not rely on the return value

Which seems to be consensus:

> Am 25.09.2016 um 21:30 schrieb Marvin Gülker <m-guelker@phoenixmail.de>:
>
> I do think that the community does not really care

I think of being explicit about the nature of a method at least as kind of
a courtesy to the caller / other programmers. Therefore, I like Robert’s
approach of at least being explicit in public methods as a reasonable
tradeoff, esp. as there’s obviously more to it than courtesy:

> Am 25.09.2016 um 19:08 schrieb Robert Klemme <shortcutter@googlemail.com > >:
>
> For public methods I usually make sure no internal data is leaked
because this would allow accidental or intentional manipulation of instance
state which likely violates the class invariant.

The risk is that someone might tie herself to this undocumented and
implicit part of the public API of a class.

> Am 25.09.2016 um 19:08 schrieb Robert Klemme <shortcutter@googlemail.com > >:
>
> the focus in Ruby is generally on pragmatic reasonable solutions and
less on strictly adhering some kind of rule system

I totally agree and wouldn’t like Ruby as much as I do if it were
differently! My intention was to get a feeling of how other developers
handle this much appreciated "freedom" offered by the language.

> Am 25.09.2016 um 21:11 schrieb Marvin Gülker <m-guelker@phoenixmail.de>:
>
> Returning `self' allows you to chain method calls. This is for example
fairly nice with operators; […]

Many thanks for your really helpful example; I’ll have to play around with
it a little bit but I think I’ve got the point of returning self now. It is
not meant as a replacement for nil for command methods, but THE return
value of this kind of (query) methods.

> Am 25.09.2016 um 21:30 schrieb Marvin Gülker <m-guelker@phoenixmail.de>:
>
> if a method has no documented return value, it is a „command method“

Hm, I’m not sure I like that one…relying on documentation? I can see your
point here, but documentation is neither a „first-class citizen“ of any
programming language I know of, nor of most of the developers I’m aware of,
including me, so it boils down to luck, which is never a good principle.
Which kind of documentation do you have in mind here?

> Am 25.09.2016 um 21:30 schrieb Marvin Gülker <m-guelker@phoenixmail.de>:
>
> I would welcome more discussions like these as well as they have become
way too rare

Good to know; I was not sure whether to start this discussion here or not
as it definitely is a slightly more general topic.

So again, a big thanks to the contributors; your input and time is really
appreciated and not taken for granted!

Cheers,
Michael

[1] Command Query Separation

Unsubscribe: <mailto:ruby-talk-request@ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-talk&gt;

8

Hi,

That’s an interesting approach:

···

Am 26.09.2016 um 23:11 schrieb Ale Miralles <amiralles.net@gmail.com>:

Another option is to create a special class just to make it clear that the method returns nothing. i.e. class Nothing;end; And have a globally accesible method that returns instances of that special class.

Returning nil would leave at least some room for interpretation, as it could stand for a command-method returning nothing or a query-method returning nil. The Nothing class would make it very unambiguous and clear. But then, on the other hand, it would lead to more code and feels a little bit over the top, although I like it.

Has anybody else used this approach?

Thanks!

Regards,
Michael

9

>
> For public methods I usually make sure no internal data is leaked
> because this would allow accidental or intentional manipulation of
> instance state which likely violates the class invariant.

The risk is that someone might tie herself to this undocumented and
implicit part of the public API of a class.

If someone relies on undocumented behaviour, that was his choice and he
has to bear all the consequences it has. Most notably he has to expect
that the method's undocumented return value may change and break at any
time a new version of the library is released. API stability for me
means stability of the documented API.

Hm, I’m not sure I like that one…relying on documentation? I can see
your point here, but documentation is neither a „first-class
citizen“ of any programming language I know of, nor of most of the
developers I’m aware of, including me, so it boils down to luck,
which is never a good principle. Which kind of documentation do you
have in mind here?

I for my part write extensive API documentation before I have anybody
use my code, so maybe I'm an exception. I spend often as much time on
documentation as on the code itself if the code is intended to be used
by anybody else than myself. When RDoc says me 100% documented, then I'm
happy.

Thus, I do mean API documentation, and an error in the documentation is
as much a bug of the software as a bug in the code itself. I use to say
that a software may be as good as it wants, if it is not documented, one
can't use it. Even more, a good documentation should not only include an
API reference, but some introductory documentation that shows you how to
use the library in general.

So, ask people to write proper documentation. File bug reports if that
documentation is missing or errorneous.

If you want an example, I am the author of the liblzma bindings for
Ruby, ruby-xz (the compression library the xz(1) programme uses). Here
is its documentation: <http://quintus.github.io/ruby-xz/&gt;\. All public
methods are documented, and the improtant ones do have the full set of
parameters/return value/example/general documentation. I should give
that library an update probably; last I touched it I wanted to change
something, but then I got busy...

Greetings
Marvin

···

On Mon, Sep 26, 2016 at 10:32:08PM +0200, Michael Schwarze wrote:

> Am 25.09.2016 um 19:08 schrieb Robert Klemme <shortcutter@googlemail.com>:

--
Blog: http://www.guelkerdev.de
PGP/GPG ID: F1D8799FBCC8BC4F

10

Hi,

[1] Command Query Separation

This article seems to be related to referential transparency.
On that point of view, it's not so useful how to discriminate between the method that return value and the one that does not in ruby, I think.

The reason is that there is exception, existence of methods that return
values and have side-effects, as mentioned too in the article.

Even if we invent the good notation bout "void methed()",
there are still many methods that have side-effects.

Regards,
Toshi

···

On 2016/09/27 5:32, Michael Schwarze wrote:

11

In cases where `nil' would be ambiguous as a return value, I have
occasionally returned an empty object assigned to a constant. The
approach looks like this:

    class Foo

      NOTHING = Object.new

      def ambiguous_method
        # do stuff
        NOTHING
      end

    end

This does not have the overhead of an entire new class and an empty
object will never be equal to anything else. If you need that one in
multiple classes of a library, place the constant inside the library's
namespacing module.

If you need some debugging luxury, you could do this:

    class Foo

      NOTHING = Object.new

      def NOTHING.inspect # :nodoc:
        "#<#{self.class} NOTHING>"
      end

      def ambiguous_method
        NOTHING
      end

    end

    f = Foo.new
    p f.ambiguous_method #=> #<Object NOTHING>

This way, as #p calls #inspect on its arguments, NOTHING will properly
identify itself to #p as a "NOTHING" object rather than some random
object (#<Object:0x00000002361350>) . The :nodoc: RDoc directive
prevents the #inspect method from being added to the documentation, as
RDoc would errorneously attribute it to the Foo class.

Greetings
Marvin

···

On Tue, Sep 27, 2016 at 08:19:51AM +0200, Michael Schwarze wrote:

Has anybody else used this approach?

--
Blog: http://www.guelkerdev.de
PGP/GPG ID: F1D8799FBCC8BC4F

12

Well, isn't that the point of a command? I am sorry, I am not sure I
got your point.

Kind regards

robert

···

On Wed, Sep 28, 2016 at 3:11 PM, Toshihiko Ichida <dogatana@gmail.com> wrote:

Hi,

On 2016/09/27 5:32, Michael Schwarze wrote:

[1] Command Query Separation

This article seems to be related to referential transparency.
On that point of view, it's not so useful how to discriminate between the
method that return value and the one that does not in ruby, I think.

The reason is that there is exception, existence of methods that return
values and have side-effects, as mentioned too in the article.

Even if we invent the good notation bout "void methed()",
there are still many methods that have side-effects.

--
[guy, jim, charlie].each {|him| remember.him do |as, often| as.you_can
- without end}
http://blog.rubybestpractices.com/

13

Hi Toshi,

Thanks for this additional perspective, which we indeed have not touched so far!

…existence of methods that return values and have side-effects, as mentioned too in the article. [1]

I totally agree, there’s no guarantee that query-methods do not change state / have side-effects. It’s the responsibility of the developer of the respective method to ensure this. But that’s at least under his control, in contrast to what the caller of the method / some other programmer might do with unintended leakage of a command-method returning "something" implicitly. That was the direction I was heading so far.

As the author of the article further states »it is a useful idiom. So I prefer to follow this principle when I can, but I’m prepared to break it».

Even if we invent the good notation bout „void methed()“, there are still many methods that have side-effects.

At least in OO languages and Ruby: »languages can’t detect them [state changing methods] automatically is that the rule about not changing state really only applies to the ObservableState of the system.« I think for this we would have to switch to the functional paradigm, I think they offer »side-effect-freeness« by design, but that’s another topic…

Cheers,
Michael

[1] Command Query Separation

···

Am 28.09.2016 um 15:11 schrieb Toshihiko Ichida <dogatana@gmail.com>:

14

Hi,

Well, isn't that the point of a command? I am sorry, I am not sure I
got your point.

I'm sorry if I confused you all.

The idea of he CQS article is that "we should divide an object's
methods into two sharply separated categories"

If there are ONLY these two types of methods, it's fine, but not.

We have THREE types of methods,
- Queries:
   Return a result and do not change the observable state of the
   system (are free of side effects).
- Queries with side effects:
   Return a result and change the observable state of the
   system
- Commands: Change the state of a system but do not return a value.

Even if we find the way to "mark" command method, it's not enough
for the original idea.

That's my point.

The method name with suffix '!' may be good for the second and
third type, but I'm not sure..

Regards,
Toshi

···

On 2016/09/28 22:29, Robert Klemme wrote:

15

Hi Michael,

in contrast to what the caller of the method / some other programmer

> might do with unintended leakage of a command-method returning "something"
> implicitly.

That was the direction I was heading so far.

> I think they offer »side-effect-freeness« by design,
> but that’s another topic…

Thank you for your explanation.
It seems that I was out of the track.

Sorry for bothering.

Regards,
Toshi

···

On 2016/09/28 22:36, Michael Schwarze wrote:

16

Hi Marvin,

Many thanks for your explanation. I didn’t want to step on anybody’s feet with my admittedly over-simplification and generalization of the documentation approach – sorry for that!

I was looking for a language feature of Ruby to handle (avoid) the implicit return of command-methods in Ruby. I’ve learned several ways how to make it explicit and that one way is to simply ignore it (the value of the implicit return). Documenting is of course a form of making the intention of a method’s style explicit. So "saying" (documenting) that it is a command-style method with no return value is definitely the right thing. But in the case of the implicit return we’ve still got the leakage issue. That’s why I prefer to additionally make my intention code-wise explicit. But that’s a personal decision and the great thing is that Ruby allows for handling it in different ways and does not prescribe the one way.

Anyway, I had a look at your referenced example [1] and your documentation is really awesome! I checked the source code on Github [2], too and it will definitely help in improving my code documentation!

Cheers,
Michael

[1] http://quintus.github.io/ruby-xz
[2] GitHub - Quintus/ruby-xz: Ruby bindings for liblzma, using fiddle

···

Am 27.09.2016 um 09:37 schrieb Marvin Gülker <m-guelker@phoenixmail.de>:

On Mon, Sep 26, 2016 at 10:32:08PM +0200, Michael Schwarze wrote:

Am 25.09.2016 um 19:08 schrieb Robert Klemme <shortcutter@googlemail.com>:

For public methods I usually make sure no internal data is leaked
because this would allow accidental or intentional manipulation of
instance state which likely violates the class invariant.

The risk is that someone might tie herself to this undocumented and
implicit part of the public API of a class.

If someone relies on undocumented behaviour, that was his choice and he
has to bear all the consequences it has. Most notably he has to expect
that the method's undocumented return value may change and break at any
time a new version of the library is released. API stability for me
means stability of the documented API.

Hm, I’m not sure I like that one…relying on documentation? I can see
your point here, but documentation is neither a „first-class
citizen“ of any programming language I know of, nor of most of the
developers I’m aware of, including me, so it boils down to luck,
which is never a good principle. Which kind of documentation do you
have in mind here?

I for my part write extensive API documentation before I have anybody
use my code, so maybe I'm an exception. I spend often as much time on
documentation as on the code itself if the code is intended to be used
by anybody else than myself. When RDoc says me 100% documented, then I'm
happy.

Thus, I do mean API documentation, and an error in the documentation is
as much a bug of the software as a bug in the code itself. I use to say
that a software may be as good as it wants, if it is not documented, one
can't use it. Even more, a good documentation should not only include an
API reference, but some introductory documentation that shows you how to
use the library in general.

So, ask people to write proper documentation. File bug reports if that
documentation is missing or errorneous.

If you want an example, I am the author of the liblzma bindings for
Ruby, ruby-xz (the compression library the xz(1) programme uses). Here
is its documentation: <http://quintus.github.io/ruby-xz/&gt;\. All public
methods are documented, and the improtant ones do have the full set of
parameters/return value/example/general documentation. I should give
that library an update probably; last I touched it I wanted to change
something, but then I got busy...

Greetings
Marvin

--
Blog: http://www.guelkerdev.de
PGP/GPG ID: F1D8799FBCC8BC4F

Unsubscribe: <mailto:ruby-talk-request@ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-talk&gt;

Mit freundlichem Gruß
Michael Schwarze

17

I favour the idea that methods not designed to return a useful value should return self. I was under the impression that this was quite common -- across languages, even.

Which would mean that it would be an additional easy "tell" for anyone reading your code. Plus it enables the extra functionality of chaining, as others have pointed out.

Click here to view Company Information and Confidentiality Notice.<http://www.jameshall.co.uk/index.php/small-print/email-disclaimer>

18

I favour the idea that methods not designed to return a useful value should return self. I was under the impression that this was quite common -- across languages, even.

There are languages which allow to define "there is no return from a
method / function". With those obviously you should not return self /
this / whatever name language designer chose for current instance.

Which would mean that it would be an additional easy "tell" for anyone reading your code. Plus it enables the extra functionality of chaining, as others have pointed out.

I am not sure whether chaining is always such a good idea. This can
soon get messy.

Kind regards

robert

···

On Tue, Sep 27, 2016 at 10:23 AM, Andy Jones <Andy.Jones@jameshall.co.uk> wrote:

--
[guy, jim, charlie].each {|him| remember.him do |as, often| as.you_can
- without end}
http://blog.rubybestpractices.com/

19

Hi Andy,

Thanks for the additional input, although it’s contrary to what I first understood of returning self:

I favour the idea that methods not designed to return a useful value should return self.

I thought of returning self as "just“ being necessary for chaining, but then I’m still not really into chaining, so that was my misunderstanding. Which leads me to having an additional option for how to return from command-methods: returning self; although I’ve to admit that at least for the time being I will stick with Ale’s Nothing class, which I really have started to like after experimenting a little bit with it!

I was under the impression that this was quite common — across languages, even.

That made me curious and I’ve searched a little bit around and found some interesting bits:
* There’s an interesting conference talk »Eastward Ho! A Clear Path Through Ruby With OO« [1] going deeper into the chaining which I’ll watch later in-depth.
* Although it’s not Ruby related, there’s an interesting discussion on Stackoverflow [2] supporting your impression and stating some interesting things for my initial CQS question
  - »In Smalltalk, every method that doesn’t explicitly return something, has an implicit "return self“«!
  - »In Python, every method that doesn’t explicitly return something, has an implicit "return None“!

Cheers,
Michael

[1] https://confreaks.tv/videos/rubyconf2014-eastward-ho-a-clear-path-through-ruby-with-oo
[2] python - Purpose of `return self` from a class method? - Software Engineering Stack Exchange

···

Am 27.09.2016 um 10:23 schrieb Andy Jones <Andy.Jones@jameshall.co.uk>:

20

Well, isn't that the point of a command? I am sorry, I am not sure I
got your point.

I'm sorry if I confused you all.

Maybe only me. :slight_smile:

The idea of he CQS article is that "we should divide an object's
methods into two sharply separated categories"

If there are ONLY these two types of methods, it's fine, but not.

We have THREE types of methods,
- Queries:
  Return a result and do not change the observable state of the
  system (are free of side effects).
- Queries with side effects:
  Return a result and change the observable state of the
  system
- Commands: Change the state of a system but do not return a value.

There could be even more classfications, e.g. add dimension of
changing arguments to this and you get SIX types... :wink:

Even if we find the way to "mark" command method, it's not enough
for the original idea.

That's my point.

Now I got it. Thank you!

The method name with suffix '!' may be good for the second and
third type, but I'm not sure..

I think since the Ruby world has not established this clear cut
distinction anything that we would do now differently would feel odd.
It's a bit similar to static typing: everybody agrees that having
compile time type information avoids bugs, especially a class of bugs
caused by using the wrong instance for assignments or method calls. In
practice we get along without it in Ruby, Python and whatnot language
pretty well. :slight_smile:

Kind regards

robert

···

On Wed, Sep 28, 2016 at 3:45 PM, Toshihiko Ichida <dogatana@gmail.com> wrote:

On 2016/09/28 22:29, Robert Klemme wrote:

--
[guy, jim, charlie].each {|him| remember.him do |as, often| as.you_can
- without end}
http://blog.rubybestpractices.com/