code review 4121051: io: add ReadRuner

io: add ReadRuner
Put it in the same package as ReadByter.
There is no implementation here for either interface.

[r, 2011-02-02 04:51:03]

Hello rsc (cc: golang-dev@googlegroups.com),

I'd like you to review this change.

[rsc, 2011-02-02 05:03:46]

LGTM

[r, 2011-02-02 05:09:37]

*** Submitted as http://code.google.com/p/go/source/detail?r=c50ac92b2a18 ***

io: add ReadRuner
Put it in the same package as ReadByter.
There is no implementation here for either interface.

R=rsc
CC=golang-dev
http://codereview.appspot.com/4121051

[gri, 2011-02-02 06:08:59]

These names seem unfortunate. If the methods were called

ByteRead
RuneRead

the interfaces could be called

ByteReader
RuneReader

- gri

On Tue, Feb 1, 2011 at 8:51 PM, <r@golang.org> wrote:

> Reviewers: rsc,
>
> Message:
> Hello rsc (cc: golang-dev@googlegroups.com),
>
> I'd like you to review this change.
>
>
> Description:
> io: add ReadRuner
> Put it in the same package as ReadByter.
> There is no implementation here for either interface.
>
> Please review this at http://codereview.appspot.com/4121051/
>
> Affected files:
>  M src/pkg/io/io.go
>
>
> Index: src/pkg/io/io.go
> ===================================================================
> --- a/src/pkg/io/io.go
> +++ b/src/pkg/io/io.go
> @@ -158,6 +158,15 @@
>        ReadByte() (c byte, err os.Error)
>  }
>
> +// ReadRuner is the interface that wraps the ReadRune method.
> +//
> +// ReadRune reads a single UTF-8 encoded Unicode character
> +// and returns the rune and its size in bytes. If no character is
> +// available, err will be set.
> +type ReadRuner interface {
> +       ReadRune() (rune int, size int, err os.Error)
> +}
> +
>  // WriteString writes the contents of the string s to w, which accepts an
> array of bytes.
>  func WriteString(w Writer, s string) (n int, err os.Error) {
>        return w.Write([]byte(s))
>
>
>

[niemeyer, 2011-02-02 11:49:27]

> These names seem unfortunate. If the methods were called
> 
> ByteRead
> RuneRead
> 
> the interfaces could be called
> 
> ByteReader
> RuneReader

Agreed.  These names feel better even if the methods themselves
are not renamed, actually.

[r, 2011-02-02 16:00:13]

I wanted to name the interface RuneReader but didn't, for consistency.
 I even considered explaining it in the CL description.

Discussion welcome.  It's very small point to change an interface
that's rarely used.  Do we do the more drastic thing of pushing the
consistency through to the methods, which are widely used?

-rob

[niemeyer, 2011-02-02 17:25:22]

> Discussion welcome.  It's very small point to change an interface
> that's rarely used.  Do we do the more drastic thing of pushing the
> consistency through to the methods, which are widely used?

I prefer ReadByte (verb + noun) slightly over ByteRead, but
ByteReader strongly over ByteRuner.

So I'm +1 on renaming the interfaces, and -0 on renaming
the methods.

[niemeyer, 2011-02-02 17:32:08]

Sorry, I just gave my opinion and forgot to give the background.

The background is that Rune and Byte are nouns, not verbs, so
Runer doesn't feel very good.  It's a bit like Wall and Waller.

[gri, 2011-02-02 18:01:12]

I'd be glad with n13m3y3r@'s suggestion: Keep the method names as is, rename
the interfaces. I'm happy to make the change if we all agree.

The only reason for suggesting the rename of the methods was to be
consistent as elsewhere (read -> reader, etc.). But the clarity of a good
name beats consistency for me in this case.

- gri


On Wed, Feb 2, 2011 at 8:00 AM, Rob 'Commander' Pike <r@golang.org> wrote:

> I wanted to name the interface RuneReader but didn't, for consistency.
>  I even considered explaining it in the CL description.
>
> Discussion welcome.  It's very small point to change an interface
> that's rarely used.  Do we do the more drastic thing of pushing the
> consistency through to the methods, which are widely used?
>
> -rob
>

[rog, 2011-02-02 18:09:56]

+1

On 2 February 2011 18:01, Robert Griesemer <gri@golang.org> wrote:
> I'd be glad with n13m3y3r@'s suggestion: Keep the method names as is, rename
> the interfaces. I'm happy to make the change if we all agree.
> The only reason for suggesting the rename of the methods was to be
> consistent as elsewhere (read -> reader, etc.). But the clarity of a good
> name beats consistency for me in this case.
> - gri
>
> On Wed, Feb 2, 2011 at 8:00 AM, Rob 'Commander' Pike <r@golang.org> wrote:
>>
>> I wanted to name the interface RuneReader but didn't, for consistency.
>>  I even considered explaining it in the CL description.
>>
>> Discussion welcome.  It's very small point to change an interface
>> that's rarely used.  Do we do the more drastic thing of pushing the
>> consistency through to the methods, which are widely used?
>>
>> -rob
>
>

[rsc, 2011-02-02 20:29:03]

Some data about the bike shed:

1. This specific case (VerbNoun -> VerbNouner vs NounVerber) hasn't
come up in tree anywhere else.  io.ReadByter is the only exported one.
There are unexported readRuners.

2. There are some VerbPreposition -> VerberPreposition also in io:
ReaderFrom, WriterTo, ReaderAt, WriterAt.

I can't find any other precedents.
I am comfortable with either ReadByter or ByteReader
as long as we stick to the decision for future names.

Russ

[r2, 2011-02-02 20:33:40]

On Feb 2, 2011, at 12:28 PM, Russ Cox wrote:

> Some data about the bike shed:
> 
> 1. This specific case (VerbNoun -> VerbNouner vs NounVerber) hasn't
> come up in tree anywhere else.  io.ReadByter is the only exported one.
> There are unexported readRuners.
> 
> 2. There are some VerbPreposition -> VerberPreposition also in io:
> ReaderFrom, WriterTo, ReaderAt, WriterAt.
> 
> I can't find any other precedents.
> I am comfortable with either ReadByter or ByteReader
> as long as we stick to the decision for future names.

I think most people want ByteReader, and gri proposes to make that change, but
the sticky point is whether we should therefore rename the method.

-rob

[niemeyer, 2011-02-02 21:04:59]

> 2. There are some VerbPreposition -> VerberPreposition also in io:
> ReaderFrom, WriterTo, ReaderAt, WriterAt.

These feel reasonable.  FromReader and ToWriter look a lot
like conversion functions rather than interfaces.

If that sounds acceptable to others as well, the rule
would be NounVerber and VerberPreposition for future work.

(but ReadFromer would be awesome ;-)

[niemeyer, 2011-02-02 21:14:16]

> I think most people want ByteReader, and gri proposes to make that change, but
> the sticky point is whether we should therefore rename the method.

There seems to be agreement as well that the method names are ok.

This specific case is interesting in fact, because the p.p.
of read is read as well, so ByteRead would mean something
else than ReadByte.

[rsc, 2011-02-02 21:21:10]

>> I am comfortable with either ReadByter or ByteReader
>> as long as we stick to the decision for future names.
>
> I think most people want ByteReader, and gri proposes to
> make that change, but the sticky point is whether we should
> therefore rename the method.

I am comfortable with either of

type ByteReader interface {
    ReadByte() (byte, os.Error)
}

type ReadByter interface {
    ReadByte() (byte, os.Error)
}

I am definitely not comfortable with

type ByteReader interface {
    ByteRead() (byte, os.Error)
}

because ByteRead contradicts the established
conventions for naming methods.  I thought only the
interface name was being decided.

Russ

[r2, 2011-02-02 21:23:20]

On Feb 2, 2011, at 1:19 PM, Russ Cox wrote:

>>> I am comfortable with either ReadByter or ByteReader
>>> as long as we stick to the decision for future names.
>> 
>> I think most people want ByteReader, and gri proposes to
>> make that change, but the sticky point is whether we should
>> therefore rename the method.
> 
> I am comfortable with either of
> 
> type ByteReader interface {
>    ReadByte() (byte, os.Error)
> }
> 
> type ReadByter interface {
>    ReadByte() (byte, os.Error)
> }
> 
> I am definitely not comfortable with
> 
> type ByteReader interface {
>    ByteRead() (byte, os.Error)
> }
> 
> because ByteRead contradicts the established
> conventions for naming methods.  I thought only the
> interface name was being decided.

Then the plan is decided.

-rob