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.
We record who made the comment, when it was made, and a strong
preference for a bug to be filed about what needs to be done.
I propose that if the developer thinks strongly enough to leave a TODO
comment for something that needs to be fixed, they should also file a
bug to track that it doesn't get lost.
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.
This is considered good programming practice.
A third thing...
Have these guidelines stored in the source code tree. Perhaps as
a HACKING document in the root?
Cheers
Tim
--
Juju-dev mailing list
Juju-dev@lists.ubuntu.com
Modify settings or unsubscribe at:
https://lists.ubuntu.com/mailman/listinfo/juju-dev
