[bind10-dev] coding guidelines

[JINMEI Tatuya / 神明達哉]

At Fri, 19 Oct 2012 11:55:14 -0700,
JINMEI Tatuya <jinmei at isc.org> wrote:

> Okay, on top of the understanding, your arguments seem to be a bit
> more convincing to me.  Considering this and some other points I have
> had (see below), my personal proposal is:
> 
> 1: consistently use <>, no "", with reasonably controlling the -I
>    path.
> 2: if we cannot agree with #1, restrict the use of "" only from .cc
>    (not in .h), and only when the "includer" and "includee" are
>    located in the same directory.
> 
> I'll explain some more details of these in a followup message.

So here are the details:

My rationale for proposal #1 is first based on the observation that
introducing "" to be error prone doesn't seem to be much effective (as
Francis argued), and also because (IMO) it's generally better to use
consistent style.  Being consistent with mixed use of <> and "" is
difficult and mostly impossibly to detect and fix in review.

If someone still wants to use "" in some cases, however, I wouldn't
strongly fight against that.  After all, this seems to be a relatively
minor preference issue, and except for style consistency the practical
pros and cons seem to be pretty marginal either way.  So if everyone
can feel happy by being more flexible, I'm okay with that.

But, in that case, I'd like to impose some restrictions to the use of
"" as proposed above.

I had one specific trouble with "" before.  There was a .cc for a test
located in lib/datasrc/memory/tests that had an include like this:
#include "../rdata_serialization_priv.cc"
(ignore the oddity of including ".cc", which is irrelevant here)
We subsequently needed to move the entire memory/tests directory to
lib/datasrc/tests/memory/tests, and I had to update this include.
This would've not had happened if it had originally been specified
with <>:
#include <datasrc/memory/rdata_serialization_priv.cc>

Of course, <> can also fail when files are moved, but if we use "", it
not only relies on the location of the target file, but also depends
on the location of its own.  Also, moving some entire directory is not
very uncommon operation, so I guess the practice of restricting the
use to the same directly is reasonably effective (of course, it cannot
help avoid all of the problems of this kind).

Restricting the use of "" to .cc is a kind of corollary to this
point.  .h files are often installed to somewhere else for public use,
and since we cannot 100% control where they are stored, it would be
prudent if we keep them as location-independent as possible (although,
of course, if .h files are stored in a very random way, it won't work
anyway whether we use "" or <>.  This is basically a relative
comparison).  While there are some .h files that aren't supposed to be
publicly installed, the policy can change in future versions so it's
safer to impose the rule without exceptions (and it's easier to detect
in review, etc).

---
JINMEI, Tatuya