<div dir="ltr"><div><div><div><div><div><div><div><div><div>Hi,<br><br></div>I would like to share an idea with you. <br><br></div>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. ;)<br><br></div>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.<br><br></div>// Copyright 2015 Canonical Ltd.<br>// Licensed under the AGPLv3, see LICENCE file for details.
<br><br></div>// Package foo is intended to provide access to the foo<br>// cloud provider. Here it ...<br></div>package foo<br><br></div>This way we not only provide a good documentation for sites like <a href="http://godoc.org">godoc.org</a> 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*).<br><br></div>So, what do you think?<br><br></div>mue<br><br></div><div dir="ltr">-- <br></div><div dir="ltr">Frank Mueller <frank.mueller<a>@canonical.com</a>><br>
Juju Core Sapphire Team <<a>http://jujucharms.com</a>></div>