James Carlson wrote: > ... > In that case, I think you might be misinformed about what "private" > means in the context of architectural review. It means that it's not > documented such that someone outside of the project or consolidation > can use it. >
That is, actually, exactly what I'm objecting to. Someone "outside the project", should be given enough minimal information, to use it. To give a very specific, personal example, of when this kind of thing is USEFUL: No-one outside of sun, was using the original USB implementation in solaris to write code. People "out here" needed drivers. Sun was too busy to write them. So I took it upon myself to write some. I spent a very long time trying to figure out where and how I should interface to things. (weeks) It finally all came together, when I managed to stumble across a single (very long) header file somewhere, that had some very nice, clear "documentation" on what the important functions, structs, etc. were. Granted, I didnt have the full source code to look at, at that time. but even if I had the source code at that time... it was really that header file, that made it possible for me to write the functional drivers that I did. This was for an interface that was considered "private" at the time. Because the team were all concerned, "oh, this is an unstable interface, we're going to change it, we wouldnt want people actually USING this thing,", yadda yadda yadda. Keeping the interface "private and officially undocumented" was the WRONG CHOICE to make I'm guessing that the USB team would still say that they made the right choice in keeping in private. However, I as a community member who was hurt by their choice, say it was the WRONG choice to make, and keeping interfaces like that private, is ALWAYS the WRONG choice to make. I wrote drivers for a "private, uncommited interface".. and that's a GOOD thing. Many people got a great amount of use out of the stuff I wrote, in spite of attempts by sun to keep it private. YES, it changed later. YES, the code I wrote isnt very useful now. But it was VERY useful *then*, to many people. I'm asking the ARC to decide to not let that type of situation happen again, at a policy level. To disallow "private" entirely. Stop trying to "protect" outside people from coding to an interface that could change. I knew it would change from the start, when I wrote my code. I didnt need to be "protected" from that, by sun keeping the interface private. (if people want an interface to be TRUELY "private", while they play with things.. then dont put it in the public opensolaris tree. If, contrariwise, it is there, then document it to some minimal degree!) > It's entirely true that some designers and implementors may leave out > comments that you feel are necessary or may fail to produce adequate > design information. I'm not talking about (high level) design information. [it would be nice, of course, to have it :) but that's not the thrust of what I'm saying here]
