Re: [Boost-users] [boost] Maintenace Guidelines wiki page
----- Original Message ----- From: "Robert Ramey" <ramey@rrsd.com> To: <boost@lists.boost.org> Cc: <boost-users@lists.boost.org> Sent: Saturday, November 22, 2008 11:28 PM Subject: Re: [boost] [Boost-users] Maintenace Guidelines wiki page
vicente.botet wrote:
----- Original Message ----- From: "Robert Ramey" <ramey@rrsd.com> To: <boost-users@lists.boost.org> Cc: <boost@lists.boost.org> Sent: Saturday, November 22, 2008 9:19 PM Subject: Re: [Boost-users] Maintenace Guidelines wiki page
I really think that *we can* achieve this goal.
I would say 'we COULD' achieve this goal - if there was a true desire to do so.
You don't belive that things COULD change?
Your "Maintainence Guidlines" presume a consensus about what should be acceptable practice where no such consensus actually exists.
Which acceptable practice are you referring to for which there is no consensus?
My view is that it is good practice to consider breaking an interface should be considered a bug.
Does your view accepts that exceptionally a well documented breaking change with a reasoable deprecated period could not be considered a bug?
The responses to the posting cited above, indicate to me that there is no consensus to support this view point.
You are right, there was no consensus at all respect to this point. May be we can reach a consensus in other points that can make Boost more backward compatible if not completly backward compatible. Do you think that the deprecation of a feature should be considered as a bug? If not how long should a reasonable period be for you? <snip> ...
Please could you participate in the elaboration of this guidelines,
Basically, the guidelines are fine Thanks. The guidelines for authors should be separated from those for users.
Yes, I could add an index by author, user, RM. Why not.
For users, "don't use "using" " could be part of a larger list of suggestions for getting the most benefit from the libraries.
I'm sure that you have think about it already. Could you share with us some of these suggestions? Thanks, Vicente
My view is that it is good practice to consider breaking an interface should be considered a bug.
Does your view accepts that exceptionally a well documented breaking change with a reasoable deprecated period could not be considered a bug?
Well, if its intentional, it's by definition not a bug - its a feature.
The responses to the posting cited above, indicate to me that there is no consensus to support this view point.
You are right, there was no consensus at all respect to this point.
May be we can reach a consensus in other points that can make Boost more backward compatible if not completly backward compatible.
We don't need a consensus to make progress. I believe that progress can be made by winning more developers to this point of view. It just takes time - lots of time spent just like this.
Do you think that the deprecation of a feature should be considered as a bug? If not how long should a reasonable period be for you?
<snip> ...
Of course it has to happen occasionally. My view is that it happens much more often than necessary. I understand that library author's want to make their works as perfect as possible. It's this exact character flaw that makes us successful at what we do. Buf if libraries want to have their libraries to be successful, they have to understand that they have to build trust with users and they can't do this by leaving them hanging out to dry. I realise that they don't think they're doing this - but they are - and I'm here to point this out.
Yes, I could add an index by author, user, RM. Why not.
Actually, I'm thinking the the a library author face entirely different problems. a library author want's to cover as much ground (compilers, user errors, use cases, etc) as possible. So suggestions like don't break an interface, use things like boost/config, Use Boost.Concepts to help your find mistakes in library usage, etc. are to him. a user want's to get done with as little as trouble and suprises as possible. So suggestions like avoiding "using" are helpful. For users, I'm thinking of suggestions similar to "Effective C++, oriented to boost. Any writing "Effective Boost"? Robert Ramey
----- Original Message ----- From: "Robert Ramey" <ramey@rrsd.com> To: <boost-users@lists.boost.org> Cc: <boost@lists.boost.org> Sent: Sunday, November 23, 2008 7:39 AM Subject: Re: [Boost-users] [boost] Maintenace Guidelines wiki page
My view is that it is good practice to consider breaking an interface should be considered a bug.
Does your view accepts that exceptionally a well documented breaking change with a reasoable deprecated period could not be considered a bug?
Well, if its intentional, it's by definition not a bug - its a feature.
Right. <snip>
Actually, I'm thinking the the a library author face entirely different problems.
Do you mean the user and the author of course.
a library author want's to cover as much ground (compilers, user errors, use cases, etc) as possible. So suggestions like don't break an interface,
I think that this guideline is implicit on the other guidelines, but I could add it explicitly.
use things like boost/config,
How boost/config helps on maintenace?
Use Boost.Concepts to help your find mistakes in library usage, etc. are to him.
Could you detail how Concepts helps on mantenance?
a user want's to get done with as little as trouble and suprises as possible. So suggestions like avoiding "using" are helpful. For users, I'm thinking of suggestions similar to "Effective C++, oriented to boost. Any writing "Effective Boost"?
Could you be more precise? Best, Vicente
Note, that I didn't really want to specifically advocate for any particular "guideline". It was an example of the kind of thing that might be important to a library author but not to a user. But I might as well go a little off topic and mention what I had in miind in these particular guide lines.
use things like boost/config,
How boost/config helps on maintenace?
boost/config contains all (or most of) the "fix ups" required to make one's code portable among various compilers and operating systems. So if one uses boost config rather than his own macros, his library will automatically be functioning when a new platform is made available in boost config. So this helps libraries cover the widest range of applicability while minimizing the amount of effort required to achive this.
Use Boost.Concepts to help your find mistakes in library usage, etc. are to him.
Could you detail how Concepts helps on mantenance?
I think the usage of boost concepts or something like it would benefit library authors. I failed to use it in the serialization library because I didn't understand how to use it at the time. I think the serialization library would have been better had I understood how to use the concept of concepts. Here is why I think so. a) Using boost concept requires that one explicitly state what the type requirements are for every template. This can and should be identical to that described in the library documentation. This avoids the problem whereby one writes the whole library and then discovers while writing the documenation that something doesn't really make sense and that things could be refactors in a better way. b) Combined with tests, this means that an interface change would trap at compiler time. Now the author who has made such a change is faced with the extra work of updating his tests and documentation in order to get things to compile. He can't accidently drop in an "obvious" improvement without realizing that he changed the interface. This is much easier to do than it would first appear and I would guess that many of the incidences where this occurs are in fact accidental. And of course this would be a huge help to someone other than the original author who needs to make some change. c) Maintaining a library whose code, tests, and documentation are not in sync is harder than maintaining a library which doesn't have this problem. Using something like concepts would make it more likely that the code in the library is in sync with the tests and documentation. This would make maintenance easier d) More precise error locations would help support users and diminish the need for mailing list support. Technically this isn't maintenance - but it is closely related since that is how bugs are found after release. HUGE caveat here is that I've never personally used boost concepts. When I really needed it, I didn't understand the documentation - in large part this is because the concept concept was a new concept to me. Now it seems that this facility will/may be built into future compilers. So I don't know if its a good idea to invest effort in implementing boost concept as it currently is stands into a current library such as serialization.
And since you've got me started there is a question about dropping one's own stuff into the boost namespace. I have a project which uses a couple of boost libraries: signals, function, thread, variant, integer - not a huge number of libraries. This contains the following symbols: boost::bind boost::function boost::variant // might be ok boost::get - in the variant library boost::mutex // all the threading types are directly in boost boost::uint_fast16_t // all these are directly in boost namespace boost::signals looks like it creates a bunch of boost::signals0, 1,etc. So far this has only been somewhat confusing. But, if boost expects to grow, this practice should probably be discouraged.
a user want's to get done with as little as trouble and suprises as possible. So suggestions like avoiding "using" are helpful. For users, I'm thinking of suggestions similar to "Effective C++, oriented to boost. Any writing "Effective Boost"?
Could you be more precise?
The only one that comes to mind right now is to avoid "using" in code which uses libraries. I'm sure that there are others that other experienced boost users could come up with. Robert Ramey
----- Original Message ----- From: "Robert Ramey" <ramey@rrsd.com> To: <boost-users@lists.boost.org> Cc: <boost@lists.boost.org> Sent: Sunday, November 23, 2008 5:36 PM Subject: Re: [Boost-users] [boost] Maintenace Guidelines wiki page
use things like boost/config,
How boost/config helps on maintenace?
boost/config contains all (or most of) the "fix ups" required to make one's code portable among various compilers and operating systems. So if one uses boost config rather than his own macros, his library will automatically be functioning when a new platform is made available in boost config. So this helps libraries cover the widest range of applicability while minimizing the amount of effort required to achive this.
I believed that no library used its owns macros. Confidentlialy could you give some examples ;-)?
Use Boost.Concepts to help your find mistakes in library usage, etc. are to him.
Could you detail how Concepts helps on mantenance?
I think the usage of boost concepts or something like it would benefit library authors. I failed to use it in the serialization library because I didn't understand how to use it at the time. I think the serialization library would have been better had I understood how to use the concept of concepts. Here is why I think so.
a) Using boost concept requires that one explicitly state what the type requirements are for every template. This can and should be identical to that described in the library documentation. This avoids the problem whereby one writes the whole library and then discovers while writing the documenation that something doesn't really make sense and that things could be refactors in a better way.
b) Combined with tests, this means that an interface change would trap at compiler time. Now the author who has made such a change is faced with the extra work of updating his tests and documentation in order to get things to compile. He can't accidently drop in an "obvious" improvement without realizing that he changed the interface. This is much easier to do than it would first appear and I would guess that many of the incidences where this occurs are in fact accidental. And of course this would be a huge help to someone other than the original author who needs to make some change.
c) Maintaining a library whose code, tests, and documentation are not in sync is harder than maintaining a library which doesn't have this problem. Using something like concepts would make it more likely that the code in the library is in sync with the tests and documentation. This would make maintenance easier
d) More precise error locations would help support users and diminish the need for mailing list support. Technically this isn't maintenance - but it is closely related since that is how bugs are found after release.
OK, I see the point. The concept specification add constraints on the interface but also on the implementation, so it is easier for the author to see when he is changing the interface because of its implementation is changing (at least I think that this is the case on C++0x concepts). The use of archetypes on the test would also help.
HUGE caveat here is that I've never personally used boost concepts. When I really needed it, I didn't understand the documentation - in large part this is because the concept concept was a new concept to me. Now it seems that this facility will/may be built into future compilers. So I don't know if its a good idea to invest effort in implementing boost concept as it currently is stands into a current library such as serialization.
Agreed.
And since you've got me started there is a question about dropping one's own stuff into the boost namespace.
I have a project which uses a couple of boost libraries: signals, function, thread, variant, integer - not a huge number of libraries. This contains the following symbols:
boost::bind boost::function boost::variant // might be ok boost::get - in the variant library boost::mutex // all the threading types are directly in boost boost::uint_fast16_t // all these are directly in boost namespace boost::signals looks like it creates a bunch of boost::signals0, 1,etc.
So far this has only been somewhat confusing. But, if boost expects to grow, this practice should probably be discouraged.
a user want's to get done with as little as trouble and suprises as possible. So suggestions like avoiding "using" are helpful. For users, I'm thinking of suggestions similar to "Effective C++, oriented to boost. Any writing "Effective Boost"?
Could you be more precise?
I belived that this was already the case, but I have not found nothing written. Vicente
participants (2)
-
Robert Ramey -
vicente.botet