[bind10-dev] coding guidelines

[Michal 'vorner' Vaner]

Hello

On Mon, Oct 15, 2012 at 02:38:27PM +0000, Francis Dupont wrote:
> > I think some tests are older than the guidelines. We didn't invest
> > the effort to fix all tests, because some were just too much work
> > with nearly no benefit.
> 
> => IMHO the "don't" should be "at lowest priority"...

I said „didn't“, not „don't“. I think they should be fixed… eventually.

> > I'm not sure about the generally usual one, but I'm sure this is not
> > the first project with Local headers first. We decided this is
> > better, because then we can test the headers have no hidden
> > dependencies.
> 
> => so you confirm the system dependencies should go in header files.
> And about config.h? where to put it?

What system dependencies? The dependencies to compile the header, yes. The ones
needed for implementation only, no. So, if I take the example of lock.{h,cc},
the pthreads.h goes to the .cc, because there's nothing in the public interface
of the wrapper that'd need it. If there was a method returning the mutex_t, then
pthreads.h would go to the header file.

And I guess config.h should go first whenever needed. But I'm not sure about
that, we don't come into contact with this one too often O:-).

> > I'd strongly disagree here. I'm OK with full relative paths in < >.
> > But the " " includes have their place. The " " ones look into
> > the local directory first.
> 
> => can I infer from your argument?
>  - " " should always a file name without a path (i.e., no '/' in it)
>  - " " doesn't make sense for a library in general
>  - " " should never refer to something in another directory (i.e.,
>   in such a case < > should be used)

I'm not sure if we understand each other. What I'm saying is, if you're
referring to „local“ header (lock.cc includes lock.h or thread.cc includes
lock.h, all of them living in one directory), then use " " without any path. If
you're using lock.h in the auth server, then use < >, because it's not local
file.

I _think_ it is OK to refer to a subdirectory of local directory by " ", so you
could do things like "rdata/generic/cname_5.h" (if these were ever included
directly) from files in dns directory. But as <dns/rdata/generic/cname_5.h> from
elsewhere.

Anyway, what I say is:
 • Use < > when including by search path.
 • Use " " if it is relative to the file into which you include.
 • Avoid search path if reasonably possible.

Which basically concludes to what I said above. But " " is not evil, it has its
place.

With regards

-- 
If you let 100 monkeys type, eventually one will write a Java program.
The rest code in Perl.

Michal 'vorner' Vaner
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: Digital signature
URL: <https://lists.isc.org/pipermail/bind10-dev/attachments/20121016/61cb6fce/attachment.bin>