On 23 August 2013 04:11, Tim Penhey <tim.pen...@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@lists.ubuntu.com
Modify settings or unsubscribe at:
https://lists.ubuntu.com/mailman/listinfo/juju-dev
