Re: [boost] Review: Boost Coding Guidelines

From: Vladimir Prus (ghost_at_[hidden])
Date: 2001-07-24 09:58:12

Having read the proposed coding guidelines, I have found that some parts are 
reasonable, some document existing practice, some are arbitrary and some are 
questionable. More details at the end of the message. On the whole, the 
document is reasonable. However, I think it should not be accepted.

Most of my reasons are already stated by others, and I only have to slightly 
elaborate. First of all, been reasonable, in my opinion, is not enough for 
boost coding guidelines. They should incorporate good points from other 
guideline and surpass them.  

The single most important thing is to refactor guidelines into boost 
conventions, semantical guidelines and syntactical ones. I would even suggest 
specifically separating semantical guidelines which affect external interface 
(and which are more important). Such refactoring will immediately make 
documents status clear:
        acceptance of boost conventions, will mean: "this arbitrary rules has been 	
agreed upon for the sake of uniformity"
        acceptance of semantical guidelines will mean: "this guidelines are 
considered reasonable by boost members, who find that doing otherwise often 
causes problems"
        acceptance of syntactical guidelines, if formal review is needed for them at 
all, will mean: "we find the suggested coding style readable and won't be 
very much embarassed if anybody use it"
Without refactoring, those different meaning will collide, and there's danger 
readers will assume second sense, which is undesirable.

Once split, boost convention are easy  to get rid of. Syntactical guidelines 
too. And semantical ones should be expanded and enhanced and detailed &c.

Last remark: David said:
        "If they are rejected, I will only wish that the formal review had begun
        earlier so that I wouldn't have spent so much time on them here."
On the contrary, I wish for more time to be spend on guidelines, so that in a 
month or too semantical guidelines will include most things that C++ 
community find reasonable. 

--
And now commets on guidelines themself:
Remark on all the document: the word "forbidded" should itself be forbidden.
1.	Ok
2. 	Ok, but 2.10 is arbitrary rule
3.	Mostly documents universal practice, except for 3.7, which is very
	questionable.
4.	Mostly arbitrary rules.
5.	Mostly arbitrary rules, except for 5.4 (spaces vs. tabs), which is
	important, but is already in library guidelines.
6.	Mostly reasonable. 6.7 -- arbitrary.
7.	Mostly reasonable, except for 7.1 and 7.15, which are really low-level
8.	Mostly reasonable,
	8.2 -- side note: maybe, somebody can give a good example where
	 protected data member is usefull? 	
9.	Reasonable, but more consideration probably needed.
10.	Ok, but seems very similar to 7. Merge, probably?
11.	Needs to be considered. 
12.	Disagree with
	12.3 -- explicit qualification of everything, IMO, is nothing but the old
			C technique of appending some prefix to names.
	12.4 -- see nothing wrong with using directive in implementation files.
			see nothing wrong with using directive with represent modules
			dependencies. Whether using directive results in
			"marauding army of crazed barbarians" depends on whether one puts
			everything in one namespace instead of making some good structure.
13.	Reasonable.
14.	14.1 Not avoid, but consider carefully.
	14.2 Why, on *all* constructors. If this is really meant, then I object.
	14.3 Never?
15.	Is it really belong here?					
-- 
Regards,
Vladimir