Policies for coding

[Nate Finch]

On the interface point, I agree with Roger. To me, this is a classic
example of good programming practice: Have your methods accept the most
general types coming in, and return the most specific types going out. This
leads to the least coupling between bits of code, while allowing the most
functionality.

If you return a concrete bufio.Reader, anyone who needs specific methods
from bufio.Reader can use those methods. However, they can still pass it in
to any method that accepts an io.Reader interface and it'll work just fine.
But until such a time as they need to pass it into something that just
wants an io.Reader, they haven't lost any of the functionality of the bufio
implementation.

The nice thing about Go is that you don't have to make sure that you pass
around interfaces everywhere, since the compiler can convert types to
interfaces "on the fly" as needed.

It does require a little discipline when creating methods to avoid the
mental default of just writing a method to take the concrete type that you
expect to receive, and instead look at what methods you use from that type
and see if it's more appropriate to use an interface that type implements.

I don't know the exact problems you were having, Tim, but maybe a more
specific example would help us (or at least me) understand the problem
you're trying to solve.



On Fri, Aug 23, 2013 at 5:37 AM, roger peppe <rogpeppe at gmail.com> wrote:

> On 23 August 2013 04:11, Tim Penhey <tim.penhey at canonical.com> wrote:
> > Hi folks,
> >
> > I have two items I'd like to propose for general policies or guidelines
> > for coding within the juju-core codebase.
> >
> > Firstly is to formalise on structure for TODO comments.  We already have
> > an informal policy around TODO (person), where person is the person that
> > most often write it, although I don't believe this is
> > always followed.
> >
> > I propose the following structure:
> >
> > // TODO (thumper): 2013-08-23 bug 1654321
> > // Details about the change needed, or things to do.
>
> This seems reasonable, but there's one down side - currently
> for most TODOs, a grep will pull out both the TODO and its
> description, whereas this will lose that.
>
> Perhaps we could do it this other way around?
>
> // TODO (thumper) Details about the change needed
> // 2013-08-23 bug 1654321
>
> > Secondly, I propose the following guideline:
> >
> >   Prefer exporting functions and interfaces to structures
> >   - unless there is a very good reason why the structure
> >     should be exported.
> >
> > A common example of a structure that should be exported is a "params"
> > type structure that groups parameters for another exported function.
> >
> > By exporting interfaces, we have more ability to mock the behaviour for
> > testing, and to change implementation details without impacting all the
> > users of the code.
>
> I don't quite get this. There's nothing about *returning* an interface
> that makes more easily mockable, AFAICS. The thing that makes things
> easier to mock is that *parameters* are interfaces, as narrow as
> possible for the code in question. Doing things this way makes it
> the responsibility of each piece of code to enable itself to be mocked,
> while allowing it to present the most natural API possible to its
> clients.
>
> For example, in the Go library, bufio.NewReader returns a concrete type,
> not an interface, but many methods and functions will accept an
> io.Reader interface
> value, which happens to be implemented by bufio.Reader.
> This is idiomatic Go, and I think it can work well.
>
> Moreover some types really don't need to be mocked, as
> they're easily created on the fly and their methods don't
> rely on anything other than the data contained within them.
> Would there be any advantage in, for example,
> passing constraints.Value around as an interface?
>
> > This is considered good programming practice.
>
> I'm concerned that this statement is much more true
> in a Java-centric world than a Go-centric one.
>
> > A third thing...
> >
> >   Have these guidelines stored in the source code tree.  Perhaps as
> >   a HACKING document in the root?
>
> +1
>
>   cheers,
>     rog.
>
> --
> Juju-dev mailing list
> Juju-dev at lists.ubuntu.com
> Modify settings or unsubscribe at:
> https://lists.ubuntu.com/mailman/listinfo/juju-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20130823/a05f6f03/attachment.html>