CODECONVENTIONS.md: added documentation on documenting code.

[vitiral]

completes #1235

[stinos]

^ should be indefinitely

[pfalcon]

Looks good to me.

[danicampora]

Isn't this obsolete now:

Header files:
Try to stick to the Plan 9 header style, where header files do not include other header files.
Don't protect a header file from multiple inclusion with #if directives.

?

[vitiral]

Thanks for the spelling suggestions @pfalcon. I did an --amend comment and pushed with -f like @dhylands suggested in my other commit. Was that the correct way to do things?

@danicampora it does seem to be outdated from other header files I've looked at, but I don't know. I could remove it in this PR if people want it removed.

[danicampora]

Thanks for the spelling suggestions @pfalcon. I did an --amend comment and pushed with -f like @dhylands suggested in my other commit. Was that the correct way to do things?

That's how I do it ;-)

@danicampora it does seem to be outdated from other header files I've looked at, but I don't know. I could remove it in this PR if people want it removed.

Let's see what others think.

[dpgeorge]

I hate to be picky on such a trivial thing, but the philosophy of what you've written here goes against itself: each point is an embellishment of the previous one! It would be enough to say "be concise". If you want to say more than that then "be concise and only write comments for things that are not obvious" would be pretty good.

[dpgeorge]

Yes the stuff about Plan 9 headers is now obsolete, but it should be removed in a separate patch.

[pfalcon]

Header conventions are addressed in 2474c2a

[dpgeorge]

Merged in f64e080.