Proposal: doc.go for each package

[Frank Mueller]

Hi,

I would like to share an idea with you.

As our codebase gets larger and larger the chance of touching areas you've
never worked before gets larger too. So you often need some time to get
behind the concepts here. So for example many testing packages we have
follow different ideas. Some only contain small helpers, others larger stub
environments as a test bed allowing to inject errors and trace calls. And
that's only testing. ;)

So my proposal is to establish the writing of a doc.go for each package
containing a high-level description (details have to be as usual at the
accodring code parts) of the intention and usage of the package. This file
only contains our copyright, this documentation, and the package statement.

// Copyright 2015 Canonical Ltd.
// Licensed under the AGPLv3, see LICENCE file for details.

// Package foo is intended to provide access to the foo
// cloud provider. Here it ...
package foo

This way we not only provide a good documentation for sites like godoc.org
but also for ourselves when walking through the code. It's a fixed anchor
for an initial orientation without searching. Sure, often this is already
in or could be done into the major package files, like here in the example
a foo.go. But having a fixed name for the doc containing file makes it more
simple to navigate to, a recursive grep through all doc files is pretty
simple, and last but not least it's more obvious if this documentation is
missing (existance check could be part of CI, sadly not a quality check
*smile*).

So, what do you think?

mue

-- 
Frank Mueller <frank.mueller at canonical.com>
Juju Core Sapphire Team <http://jujucharms.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20150826/e11a3106/attachment.html>