Hi guys.
The BFAV has become the technical basis for harvesting progress. In this it has improved the rate of harvesting by removing much of the dirty work that was involved in the old processes. It has improved the efficiency of the approvals many fold.
It has also allowed us to elaborate the process by adding the quality tags, and for the first time having a more or less closed list of patches to be dealt with.
The purpose of the QA tags was to distribute the work of harvesting among more people, by allowing casual participants to help by reviewing or testing code without accepting the responsibility of the formal role of harvester.
As the efficiency of approvals went up, and we have an in-squeak list of posts and their full status, it has become much more visible that our bottleneck is not approvals. It is very clearly in the reviewing/testing stage. The reasons are very clear - rather few people help with the reviews/testing, and that quite sporadically.
This bottleneck is a result of our current structure, and won't go away by itself. It causes a situation where most patches meant for the squeak image are ignored. I think this is not likely to last - either we balance this by removing the bottleneck, or contributors of patches will balance it by posting less, an outcome I find regrettable.
In fact, I think it likely that people are already deciding not to post fixes they have available because they're likely to be ignored. Therefore, I think that if we can remove the bottleneck, and reach a state where patches submitted are all processed in reasonable time, we will get far more patches, and be able to make much better progress than we are now.
I think the following steps are in order - 1. We want to lower the barriers to casual participation. So, the BFAV, as a prerequisite for participating, should never be absent for anyone. It should be included in the base image. 2. We should improve and simplify the tools to help reviewers/testers do their job. - ClassBoxes, when they're ready, could become a big aid to testing, by allowing patches to be installed temporarily and then completely removed. - The BFAV should be improved, especially for casual users. Brent, I recommend to open its development so more people can help with this. The Swiki page is already pretty good, just point to it from the help in the BFAV. Also it might be good that its future development be carried on using Monticello, to make it easier to create and integrate improvements. 3. The current flood of BFAV traffic makes people automatically ignore the harvesting process. Therefore it MUST be selectively moved away from squeak-dev. Cees, or whoever has administrative rights on lists.sqf.org, can you please create a new mailing list called "squeak-harvest"? This fits Berts existing filters. Having this list would allow some selectivity without losing information. 4. When all is said and done, many people currently won't participate no matter how low the barriers are made, because of different priorities. Some of this is obviously reasonable, people need to pay the rent and play with whats fun for them, of course. But some of this is IMO not reasonable, and comes from a misperception. I think the NewLook code showcases this very clearly. The voices for its inclusion are very loud, but nobody bothers to review it, therefore, it isn't included. So I guess that the people doing the requesting somehow fail to perceive that the condition for inclusion is within their grasp. Of course, I could just be wrong about this. Ideas to solve this or alternative explanations would be welcome.
Daniel
I don't have time just at the moment to address all of this but I would like to request that we NOT start another mailing list. I want to discourage this because once two mailing lists exist to which BFAV traffic can be sent then the BFAV server must subscribe to both lists. We will very quickly find people sending traffic to both lists and then it will become necessary to start checking the history of received messages to be sure that a new message is not a repeat. I see no reason that posts that do not need to go to the mailing list can not be perfectly well archived within Bert's bug/fix archives and within the new BFAV server. I haven't done the work to accept such messages directly into the BFAV yet but it's just a matter of a few minutes to do so.
While on this subject I would like to request that we adopt a more intention revealing method of indicating that a message is intended to be archived into the bug system than the List-Id: header. Perhaps something like
X-Squeak-Archive-BugFix: Yes
Additional data, if needed, could be appended to this as desired.
Ken
On Thursday, October 16, 2003, at 08:57 AM, Daniel Vainsencher wrote:
This bottleneck is a result of our current structure, and won't go away by itself. It causes a situation where most patches meant for the squeak image are ignored. I think this is not likely to last - either we balance this by removing the bottleneck, or contributors of patches will balance it by posting less, an outcome I find regrettable.
Daniel,
I thought about this a little bit after our discussion on IRC. I think one of the problems may be that for many patches, nobody feels a sense of personal responsibility to review it - they don't have a reason to care about that patch in particular rather than any of the hundreds of other patches, and likely they don't feel qualifed to - they don't think they know the subsystem that the patch is affecting well enough to give a useful opinion, etc. And so they leave it for some fictional person who cares more, or is more qualified, and that person never comes.
I think that a push to get maintainers, or groups of maintainers, for the individual packages that make up the image may drastically improve the harvesting process. We don't have to have a high barrier for maintainership - we want to ensure that lots of people to participate. But rather than encourage people to harvest fixes for the big, scary, messy image, why not encourage people to sign up as part of the maintainer group for a particular package that's of interest to them? That may add the extra specificity to trigger the sense of responsibility and qualification that is needed.
Thoughts?
Avi
Hi Daniel,
Ideas to solve this or alternative explanations would be welcome.
Let me throw in a few thoughts on this issue. Speaking only for myself I find the following issues interesting/relevant in this context:
* External reviews
A key problem with external reviews is that you have to know the area involved very well to judge the wider implications of changes. It is not surprising that typically a few people review certain areas since that's their primary area of expertise. One of the key problems in the current process is that these people need reviews themselves - even though they are experts in the area and an external review is likely to just say "sure it works - what did you expect"? Or even worse, there simply isn't anybody who feels confident to review that code (who exactly even _could_ review Ned's and my joint changes for adding/removing morphs?)
Here's an interesting observation about myself: I tend to _not_ look at code from people I consider "experts" unless I am suspecting something non-obvious or outright questionable. In all other cases my basic inclination is "go ahead - if there's a problem we can fix that too" rather than think ahead and try to foresee what might be affected (which doesn't work anyway).
Personally, there are various people which I would immediately endorse to submit fixes and enhancements in various areas. In other words, I trust those people enough to be willing to live with their changes without having to explicitly review them. And yes, things will break but they'd break with or without a review by someone who doesn't really understand it. If so, what's the point?
* External testing
If you look at the traffic on Squeak-dev, I think you'll find many more responses that just say "thanks! that did it" than "[er, et]" or whatever tags. The problem is that feedback from people using a fix is mostly informal (if at all present). In a perfect world, I would want something that I can flag as a fix for some problem. When some person installs the fix the person should (later) get asked "did this solve your problem?" with a choice of "don't know yet", "yes", "no", "yes but ..." (as in: it fixes the problem but shows another one), and "no but ..." (as in: it doesn't but I have package Foo and Bar loaded which might interfere).
One way to solicit this feedback would be to install in particular [FIX]es in a way that the system _knows_ this is a fix and can ask the user about it after that fix has been in use for a while. Again, here's an example: Someone posts a fix for a problem. I load it and keep going. Some time later (perhaps when I am about to save/quit the image) the system reminds me that I have a bunch of fixes loaded and whether I'd want to comment on them. If I choose to, I get the above mentioned options and this feedback is then automatically sent to the list.
The key point about [et] tags for fixes is that people are individually bitten by the bugs and that loosing feedback from a single person means loosing _all_ of the feedback here. You don't run a [fix] right away unless you're bitten by it.
Cheers, - Andreas
-----Original Message----- From: squeakfoundation-bounces@lists.squeakfoundation.org [mailto:squeakfoundation-bounces@lists.squeakfoundation.org] On Behalf Of Daniel Vainsencher Sent: Thursday, October 16, 2003 5:57 PM To: squeakfoundation@lists.squeakfoundation.org Cc: ken@kencausey.com; Brent Vukmer; Cees de Groot; Bert Freudenberg Subject: [Squeakfoundation]The Harvesting process and the BFAV
Hi guys.
The BFAV has become the technical basis for harvesting progress. In this it has improved the rate of harvesting by removing much of the dirty work that was involved in the old processes. It has improved the efficiency of the approvals many fold.
It has also allowed us to elaborate the process by adding the quality tags, and for the first time having a more or less closed list of patches to be dealt with.
The purpose of the QA tags was to distribute the work of harvesting among more people, by allowing casual participants to help by reviewing or testing code without accepting the responsibility of the formal role of harvester.
As the efficiency of approvals went up, and we have an in-squeak list of posts and their full status, it has become much more visible that our bottleneck is not approvals. It is very clearly in the reviewing/testing stage. The reasons are very clear - rather few people help with the reviews/testing, and that quite sporadically.
This bottleneck is a result of our current structure, and won't go away by itself. It causes a situation where most patches meant for the squeak image are ignored. I think this is not likely to last - either we balance this by removing the bottleneck, or contributors of patches will balance it by posting less, an outcome I find regrettable.
In fact, I think it likely that people are already deciding not to post fixes they have available because they're likely to be ignored. Therefore, I think that if we can remove the bottleneck, and reach a state where patches submitted are all processed in reasonable time, we will get far more patches, and be able to make much better progress than we are now.
I think the following steps are in order -
- We want to lower the barriers to casual participation. So,
the BFAV, as a prerequisite for participating, should never be absent for anyone. It should be included in the base image. 2. We should improve and simplify the tools to help reviewers/testers do their job.
- ClassBoxes, when they're ready, could become a big aid to
testing, by allowing patches to be installed temporarily and then completely removed.
- The BFAV should be improved, especially for casual users. Brent, I
recommend to open its development so more people can help with this. The Swiki page is already pretty good, just point to it from the help in the BFAV. Also it might be good that its future development be carried on using Monticello, to make it easier to create and integrate improvements. 3. The current flood of BFAV traffic makes people automatically ignore the harvesting process. Therefore it MUST be selectively moved away from squeak-dev. Cees, or whoever has administrative rights on lists.sqf.org, can you please create a new mailing list called "squeak-harvest"? This fits Berts existing filters. Having this list would allow some selectivity without losing information. 4. When all is said and done, many people currently won't participate no matter how low the barriers are made, because of different priorities. Some of this is obviously reasonable, people need to pay the rent and play with whats fun for them, of course. But some of this is IMO not reasonable, and comes from a misperception. I think the NewLook code showcases this very clearly. The voices for its inclusion are very loud, but nobody bothers to review it, therefore, it isn't included. So I guess that the people doing the requesting somehow fail to perceive that the condition for inclusion is within their grasp. Of course, I could just be wrong about this. Ideas to solve this or alternative explanations would be welcome.
Daniel _______________________________________________ Squeakfoundation mailing list Squeakfoundation@lists.squeakfoundation.org http://lists.squeakfoundation.org/listinfo/squeakfoundation
- External reviews
A key problem with external reviews is that you have to know the area involved very well to judge the wider implications of changes. It is not surprising that typically a few people review certain areas since that's their primary area of expertise. One of the key problems in the current process is that these people need reviews themselves - even though they are experts in the area and an external review is likely to just say "sure it works - what did you expect"? Or even worse, there simply isn't anybody who feels confident to review that code (who exactly even _could_ review Ned's and my joint changes for adding/removing morphs?)
Exact! That's why I browse it and approved it. That's why this would be cool that you too pair a bit to have a look at some enh pending at the morphic level.
Here's an interesting observation about myself: I tend to _not_ look at code from people I consider "experts" unless I am suspecting something non-obvious or outright questionable. In all other cases my basic inclination is "go ahead - if there's a problem we can fix that too" rather than think ahead and try to foresee what might be affected (which doesn't work anyway).
Same here, even I read when I have time to learn and check if the code is not completely strange because we can always forget a method somewhere.
Personally, there are various people which I would immediately endorse to submit fixes and enhancements in various areas. In other words, I trust those people enough to be willing to live with their changes without having to explicitly review them. And yes, things will break but they'd break with or without a review by someone who doesn't really understand it.
I agree this is why we should have a fast approved track and a lot of alpha testers.
If so, what's the point?
Andreas I have the impression that having two persons per area at minimum would be cool. because it puts just more pressure on you this is like pair programming. I'm lazy while when I know that somebody else will have a look I pay attention.
- External testing
If you look at the traffic on Squeak-dev, I think you'll find many more responses that just say "thanks! that did it" than "[er, et]" or whatever tags. The problem is that feedback from people using a fix is mostly informal (if at all present). In a perfect world, I would want something that I can flag as a fix for some problem. When some person installs the fix the person should (later) get asked "did this solve your problem?" with a choice of "don't know yet", "yes", "no", "yes but ..." (as in: it fixes the problem but shows another one), and "no but ..." (as in: it doesn't but I have package Foo and Bar loaded which might interfere).
One way to solicit this feedback would be to install in particular [FIX]es in a way that the system _knows_ this is a fix and can ask the user about it after that fix has been in use for a while. Again, here's an example: Someone posts a fix for a problem. I load it and keep going. Some time later (perhaps when I am about to save/quit the image) the system reminds me that I have a bunch of fixes loaded and whether I'd want to comment on them. If I choose to, I get the above mentioned options and this feedback is then automatically sent to the list.
Yes this is a good idea. In particular the fact that the fixes may not have been exercised requires that the person choose to report. I think that this is a good way to involve concrete feedback.
The key point about [et] tags for fixes is that people are individually bitten by the bugs and that loosing feedback from a single person means loosing _all_ of the feedback here. You don't run a [fix] right away unless you're bitten by it.
Cheers,
- Andreas
-----Original Message----- From: squeakfoundation-bounces@lists.squeakfoundation.org [mailto:squeakfoundation-bounces@lists.squeakfoundation.org] On Behalf Of Daniel Vainsencher Sent: Thursday, October 16, 2003 5:57 PM To: squeakfoundation@lists.squeakfoundation.org Cc: ken@kencausey.com; Brent Vukmer; Cees de Groot; Bert Freudenberg Subject: [Squeakfoundation]The Harvesting process and the BFAV
Hi guys.
The BFAV has become the technical basis for harvesting progress. In this it has improved the rate of harvesting by removing much of the dirty work that was involved in the old processes. It has improved the efficiency of the approvals many fold.
It has also allowed us to elaborate the process by adding the quality tags, and for the first time having a more or less closed list of patches to be dealt with.
The purpose of the QA tags was to distribute the work of harvesting among more people, by allowing casual participants to help by reviewing or testing code without accepting the responsibility of the formal role of harvester.
As the efficiency of approvals went up, and we have an in-squeak list of posts and their full status, it has become much more visible that our bottleneck is not approvals. It is very clearly in the reviewing/testing stage. The reasons are very clear - rather few people help with the reviews/testing, and that quite sporadically.
This bottleneck is a result of our current structure, and won't go away by itself. It causes a situation where most patches meant for the squeak image are ignored. I think this is not likely to last - either we balance this by removing the bottleneck, or contributors of patches will balance it by posting less, an outcome I find regrettable.
In fact, I think it likely that people are already deciding not to post fixes they have available because they're likely to be ignored. Therefore, I think that if we can remove the bottleneck, and reach a state where patches submitted are all processed in reasonable time, we will get far more patches, and be able to make much better progress than we are now.
I think the following steps are in order -
- We want to lower the barriers to casual participation. So,
the BFAV, as a prerequisite for participating, should never be absent for anyone. It should be included in the base image. 2. We should improve and simplify the tools to help reviewers/testers do their job.
- ClassBoxes, when they're ready, could become a big aid to
testing, by allowing patches to be installed temporarily and then completely removed.
- The BFAV should be improved, especially for casual users. Brent, I
recommend to open its development so more people can help with this. The Swiki page is already pretty good, just point to it from the help in the BFAV. Also it might be good that its future development be carried on using Monticello, to make it easier to create and integrate improvements. 3. The current flood of BFAV traffic makes people automatically ignore the harvesting process. Therefore it MUST be selectively moved away from squeak-dev. Cees, or whoever has administrative rights on lists.sqf.org, can you please create a new mailing list called "squeak-harvest"? This fits Berts existing filters. Having this list would allow some selectivity without losing information. 4. When all is said and done, many people currently won't participate no matter how low the barriers are made, because of different priorities. Some of this is obviously reasonable, people need to pay the rent and play with whats fun for them, of course. But some of this is IMO not reasonable, and comes from a misperception. I think the NewLook code showcases this very clearly. The voices for its inclusion are very loud, but nobody bothers to review it, therefore, it isn't included. So I guess that the people doing the requesting somehow fail to perceive that the condition for inclusion is within their grasp. Of course, I could just be wrong about this. Ideas to solve this or alternative explanations would be welcome.
Daniel _______________________________________________ Squeakfoundation mailing list Squeakfoundation@lists.squeakfoundation.org http://lists.squeakfoundation.org/listinfo/squeakfoundation
Squeakfoundation mailing list Squeakfoundation@lists.squeakfoundation.org http://lists.squeakfoundation.org/listinfo/squeakfoundation
On Thu, Oct 16, 2003 at 09:57:27PM +0200, ducasse wrote:
feels confident to review that code (who exactly even _could_ review Ned's and my joint changes for adding/removing morphs?)
Exact! That's why I browse it and approved it. That's why this would be cool that you too pair a bit to have a look at some enh pending at the morphic level.
There is even between the harvesters a somewhat different view of what "review" means. Some try to *really* understand everything about a change, up to the point that the time invested is equal of having done the whole thing themselves.
As this seems to be the consesus among the Guides, I tried to do this (to some extend) myself. But I personally think this does not work: There is nobody who want's to do this, and those who do, burn just too much time with it.
I would prefer a more Agile approach to harvesting. First: I'd like to approve stuff that I filed in, that worked, and that looked not totally strange when looking over the code.
I mean, what do we gain from not adding a fix done by someone who allready submitted a lot of patches, just because nobody has the time to really understand the fix? In the end, it's not fixed. Just that.
We really need to think about what the worst case of a more agile review policy would be.
1) It could introduce a bug. Hey, what is the problem? That's what alpha is for. And bugs are good, because bugs generate tests.
2) It could be not-that-perfectly documented. To me, the alternative seems to be: Not adding, or adding a slightly-not-perfect thing. What is worse? I would *really* prefer to e.g. have some feature now instead of waiting indefinitly. But that may only be me.
Make it green. Then refactor.
Marcus
Marcus Denker marcus@ira.uka.de wrote: [SNIP]
I would prefer a more Agile approach to harvesting. First: I'd like to approve stuff that I filed in, that worked, and that looked not totally strange when looking over the code.
I mean, what do we gain from not adding a fix done by someone who allready submitted a lot of patches, just because nobody has the time to really understand the fix? In the end, it's not fixed. Just that.
We really need to think about what the worst case of a more agile review policy would be.
It could introduce a bug. Hey, what is the problem? That's what alpha is for. And bugs are good, because bugs generate tests.
It could be not-that-perfectly documented. To me, the alternative seems to be: Not adding, or adding a slightly-not-perfect thing. What is worse? I would *really* prefer to e.g. have some feature now instead of waiting indefinitly. But that may only be me.
Make it green. Then refactor.
As always, I agree in principle but I will *always* repeat this: Class comments and "top" method comments should be written when the code is written.
That does not imply "perfectly-documented" - it rather implies "documented *at all*". And I strongly urge people to think about this - why is the image so poorly commented? Because SqC took exactly this approach - "better to getthe stuff in, who cares, we can write comments later". Surprise! There is no "later" when it comes to code comment.
Now, after his little rant - I agree with you Marcus. I just want the little, little, little rule added: "Just make sure the damn code has proper code comments!"
That will save us all time in the end. It takes very little time for the author to write these comments when he has the code in his mind. And it will save hours of thought for all the rest of us.
regards, Göran
PS. And you all know that when I say "proper code comments" I am not proposing some extreme form of silly comments stating obvious things etc. And not for setters/getters. And not "in code comments".
On Fri, Oct 17, 2003 at 11:13:31AM +0100, goran.krampe@bluefish.se wrote:
As always, I agree in principle but I will *always* repeat this: Class comments and "top" method comments should be written when the code is written.
That does not imply "perfectly-documented" - it rather implies "documented *at all*". And I strongly urge people to think about this - why is the image so poorly commented? Because SqC took exactly this approach - "better to getthe stuff in, who cares, we can write comments later". Surprise! There is no "later" when it comes to code comment.
Now, after his little rant - I agree with you Marcus. I just want the little, little, little rule added: "Just make sure the damn code has proper code comments!"
Ok. Then we add a button to the CodeBrowser that generates a SUnit test that tests for the comment, generates a changeset, sends it to the list with [Tests] suffix. So the reviewer can approve the fix, and at the same time force the community to revisit that paritcular method. Same for Class comments.
Marcus
And I strongly urge people to think about this - why is the image so poorly commented? Because SqC took exactly this approach - "better to getthe stuff in, who cares, we can write comments later".
Err ... actually this is wrong. Really, we never intended to "write comments later". We were no vendor just a bunch of people willing to share their (unfinished) tools with the rest of the world. If you expect a fully documented system then find a vendor. That's what they do.
Cheers, - Andreas
"Andreas Raab" andreas.raab@gmx.de wrote:
And I strongly urge people to think about this - why is the image so poorly commented? Because SqC took exactly this approach - "better to getthe stuff in, who cares, we can write comments later".
Err ... actually this is wrong. Really, we never intended to "write comments later".
True. You probably didn't think like I wrote it. I take that back! And you probably had your reasons - you didn't intend to go open source etc, it was your own "box" and it was of course all up to you how you worked etc. I didn't imply any blaim. :-)
But nevertheless the net effect is the same unfortunately - and I don't think we should go on doing the same mistake. If anyone disagrees with this I am all ears, please tell me why it would be good to insert uncommented code into Squeak. And, no - again I am of course not talking about setters/getters.
We were no vendor just a bunch of people willing to share their (unfinished) tools with the rest of the world. If you expect a fully documented system then find a vendor. That's what they do.
First if all - I don't expect a "fully documented system". But I do want Squeak to improve in this respect because it just isn't good. And we all know that.
But again, I expressed myself wrongly.
Sorry.
regards, Göran
Hi Göran,
Err ... actually this is wrong. Really, we never intended to "write comments later".
True. You probably didn't think like I wrote it. I take that back! And you probably had your reasons - you didn't intend to go open source etc, it was your own "box" and it was of course all up to you how you worked etc. I didn't imply any blame. :-)
I didn't read any in your message ;-) I just wanted to point out that your logical conclusions have a wrong premise. And as you all know logic teaches us that starting from a wrong premise we can come to any conclusion we want ;-)
But nevertheless the net effect is the same unfortunately - and I don't think we should go on doing the same mistake.
That's (where I think) you are wrong. At least if by "doing the same mistake" you mean to "intend to write comments later". We never intended that.
If anyone disagrees with this I am all ears, please tell me why it would be good to insert uncommented code into Squeak.
It isn't good - in my understanding it is simply unavoidable in various areas if you have an incrementally developing system. Personally, I have found that if I "write comments first" they almost always end up wrong as at this time I can't cover the workings of a certain class in detail yet. So it is very likely that I decide to do some things differently somewhere down the line and then the (early) comment ends up wrongly. If I want _accurate_ comments I always write them after the fact.
Incidentally, this is one of the major differences I see with respect to comments vs. tests. Tests are kept pretty much "automatically in sync" with the actual code so (for example) as far as boundary conditions go tests document the code much better than any comment could. This is not true for overall design issues (at which tests are horrible) but for many situations a test can be (at least) as helpful as a comment.
Cheers, - Andreas
"Andreas Raab" andreas.raab@gmx.de wrote:
Hi Göran,
Err ... actually this is wrong. Really, we never intended to "write comments later".
True. You probably didn't think like I wrote it. I take that back! And you probably had your reasons - you didn't intend to go open source etc, it was your own "box" and it was of course all up to you how you worked etc. I didn't imply any blame. :-)
I didn't read any in your message ;-) I just wanted to point out that your
Good. :)
logical conclusions have a wrong premise. And as you all know logic teaches us that starting from a wrong premise we can come to any conclusion we want ;-)
True, I took it back.
But nevertheless the net effect is the same unfortunately - and I don't think we should go on doing the same mistake.
That's (where I think) you are wrong. At least if by "doing the same mistake" you mean to "intend to write comments later". We never intended that.
Ok, let me rephrase it then: "Let's not continue putting uncommented code into the image as was done previously.".
I just don't care about the reasons - but if you ask me (you don't but I pretend you do :-) ) personally I still think it was a pretty dumb move. In my experience taking the decision to not take the time to write "proper comments" always bites back sometime in the future. And as you can see - even though you couldn't possibly predict the windling road of Squeak - it bit back this time too.
If anyone disagrees with this I am all ears, please tell me why it would be good to insert uncommented code into Squeak.
It isn't good - in my understanding it is simply unavoidable in various areas if you have an incrementally developing system. Personally, I have found that if I "write comments first" they almost always end up wrong as at this time I can't cover the workings of a certain class in detail yet. So it is very likely that I decide to do some things differently somewhere down the line and then the (early) comment ends up wrongly. If I want _accurate_ comments I always write them after the fact.
Sure, now we are talking about the varius states during development. Fine, different developers work differently. But nevertheless there comes a point in development when the code you write suddenly becomes the code *I read*. In a team that point in time can come quickly - right after you commit it to our shared repo. In open source it comes after first public release.
It is *at that point* that I think the code should include comments. And I find it amazing that I need to argue for this! Come on people! XP sure is nice, but when people use those ideas to simply "get away from needing to explain things to others", I get annoyed.
Incidentally, this is one of the major differences I see with respect to comments vs. tests. Tests are kept pretty much "automatically in sync" with the actual code so (for example) as far as boundary conditions go tests document the code much better than any comment could. This is not true for overall design issues (at which tests are horrible) but for many situations a test can be (at least) as helpful as a comment.
I agree - and if you read about my "Magic Book" ideas you know that I would like to leverage that fact even more.
But... :-) I *still* think proper simple comments is something that should be written! Hey, call me old-fashioned.
Cheers,
- Andreas
Cheers, Göran
I agree goran. We should find the right level. What I tend to do is trust some people, still looking at their code this way I learn also some hidden parts of the system. Then when I'm really expert in one point, I really read.
Stef
On Vendredi, oct 17, 2003, at 12:13 Europe/Zurich, goran.krampe@bluefish.se wrote:
Marcus Denker marcus@ira.uka.de wrote: [SNIP]
I would prefer a more Agile approach to harvesting. First: I'd like to approve stuff that I filed in, that worked, and that looked not totally strange when looking over the code.
I mean, what do we gain from not adding a fix done by someone who allready submitted a lot of patches, just because nobody has the time to really understand the fix? In the end, it's not fixed. Just that.
We really need to think about what the worst case of a more agile review policy would be.
It could introduce a bug. Hey, what is the problem? That's what alpha is for. And bugs are good, because bugs generate tests.
It could be not-that-perfectly documented. To me, the alternative seems to be: Not adding, or adding a slightly-not-perfect thing. What is worse? I would *really* prefer to e.g. have some feature now instead of waiting indefinitly. But that may only be me.
Make it green. Then refactor.
As always, I agree in principle but I will *always* repeat this: Class comments and "top" method comments should be written when the code is written.
That does not imply "perfectly-documented" - it rather implies "documented *at all*". And I strongly urge people to think about this - why is the image so poorly commented? Because SqC took exactly this approach - "better to getthe stuff in, who cares, we can write comments later". Surprise! There is no "later" when it comes to code comment.
Now, after his little rant - I agree with you Marcus. I just want the little, little, little rule added: "Just make sure the damn code has proper code comments!"
That will save us all time in the end. It takes very little time for the author to write these comments when he has the code in his mind. And it will save hours of thought for all the rest of us.
regards, Göran
PS. And you all know that when I say "proper code comments" I am not proposing some extreme form of silly comments stating obvious things etc. And not for setters/getters. And not "in code comments". _______________________________________________ Squeakfoundation mailing list Squeakfoundation@lists.squeakfoundation.org http://lists.squeakfoundation.org/listinfo/squeakfoundation
goran.krampe@bluefish.se wrote:
As always, I agree in principle but I will *always* repeat this: Class comments and "top" method comments should be written when the code is written.
That does not imply "perfectly-documented" - it rather implies "documented *at all*". And I strongly urge people to think about this - why is the image so poorly commented? Because SqC took exactly this approach - "better to getthe stuff in, who cares, we can write comments later". Surprise! There is no "later" when it comes to code comment.
Now, after his little rant - I agree with you Marcus. I just want the little, little, little rule added: "Just make sure the damn code has proper code comments!"
One thing I'm planning to work on (once I'm caught up with incorporating approved items) is a simple changeset-checker which any changeset intended for inclusion must "pass". It could require that a changeset must have class comments in place, a preamble, and other basics. The checker could be invoked when doing a "mail to list" in the change sorter, for example...
- Doug
First of all, I agree with almost everything said up to this point. :-)
1. Avi points out one of the most important things that we have been talking about for ages. We need to "stake out" the packages. It is all about trust, sense of ownership and responsibility and motivation. Very important. Very. :-) We called it Stewards but we never got around to "appoint" them so it kinda stalled. Fortunately the (few) packages actually broken out where appointed maintainers simply because you *need* to enter that when they are registered. :)
In short - we need to start staking out the image with Stewards. Adam Spitz IIRC posted a great list of packages currently isolated in the image and a few people stepped forward. Let us simply delegate this task to one of the Guides to coordinate. Anyone up to it? Ned? Tim? That task is for starters to simply take that list and put names on the packages. The next step is how to do the stakeout in practice (Avi probably has ideas with PI etc).
2. We probably need to "loosen up" the harvesting process. What I mean is that, as Andreas points out, I think we need to trust each other a bit more. At least we need to trust "the experts" a bit more. Most other open source projects simply trust the developers to commit - and then fix things when they break. For example, when Ned makes fixes to Morphic I trust him. There are various constraints we can have - like for example letting people "commit" when in alpha only etc.
The only single problem I have with "trusting the experts" is that I actually *don't* trust anyone when it comes to *comments*. I am sorry to say, but most of you (sure, I make mistakes too sometimes) simply suck at commenting your code - even the best of you. ;-) ;-) <- Two smileys here - but I am actually dead serious. On the other hand - such a check can be automated, at least making sure that new classes have a class comment longer than one sentence, and perhaps methods consisting of more than 3 lines of code should also IMHO have a "top" comment.
Also, bullet #1 above would IMHO also mean that the Stewards should be free to "commit" on their own.
Well, my 2 cents.
I think BFAV and the harvesting has worked pretty good - don't get me wrong. And all work with it has been done by others than me. But I think the current process has problems and that we can do even better.
regards, Göran
goran. I can share an experiment we did with comments. In SmallWiki we generate part of the documentation automatically and we use the method comments. I can tell you that when the first time lukas did that this was empty and slowly but surely this was improving. I think that javadoc is a stupid but powerful tools to push comment. The problem is that right now the comment (class comments) do not really exist because they are not present on the screen. I do not know the solution but I can convert the code from lukas to squeak: it generates latex. But for now the solution should be within the image I guess. and I agree with you for the class comment and method comment (even if I was a lose harvester in the past :)) Stef
On Vendredi, oct 17, 2003, at 11:49 Europe/Zurich, goran.krampe@bluefish.se wrote:
First of all, I agree with almost everything said up to this point. :-)
- Avi points out one of the most important things that we have been
talking about for ages. We need to "stake out" the packages. It is all about trust, sense of ownership and responsibility and motivation. Very important. Very. :-) We called it Stewards but we never got around to "appoint" them so it kinda stalled. Fortunately the (few) packages actually broken out where appointed maintainers simply because you *need* to enter that when they are registered. :)
In short - we need to start staking out the image with Stewards. Adam Spitz IIRC posted a great list of packages currently isolated in the image and a few people stepped forward. Let us simply delegate this task to one of the Guides to coordinate. Anyone up to it? Ned? Tim? That task is for starters to simply take that list and put names on the packages. The next step is how to do the stakeout in practice (Avi probably has ideas with PI etc).
- We probably need to "loosen up" the harvesting process. What I mean
is that, as Andreas points out, I think we need to trust each other a bit more. At least we need to trust "the experts" a bit more. Most other open source projects simply trust the developers to commit - and then fix things when they break. For example, when Ned makes fixes to Morphic I trust him. There are various constraints we can have - like for example letting people "commit" when in alpha only etc.
The only single problem I have with "trusting the experts" is that I actually *don't* trust anyone when it comes to *comments*. I am sorry to say, but most of you (sure, I make mistakes too sometimes) simply suck at commenting your code - even the best of you. ;-) ;-) <- Two smileys here - but I am actually dead serious. On the other hand - such a check can be automated, at least making sure that new classes have a class comment longer than one sentence, and perhaps methods consisting of more than 3 lines of code should also IMHO have a "top" comment.
Also, bullet #1 above would IMHO also mean that the Stewards should be free to "commit" on their own.
Well, my 2 cents.
I think BFAV and the harvesting has worked pretty good - don't get me wrong. And all work with it has been done by others than me. But I think the current process has problems and that we can do even better.
regards, Göran _______________________________________________ Squeakfoundation mailing list Squeakfoundation@lists.squeakfoundation.org http://lists.squeakfoundation.org/listinfo/squeakfoundation
On Friday 17 October 2003 2:49 am, goran.krampe@bluefish.se wrote:
In short - we need to start staking out the image with Stewards. Adam Spitz IIRC posted a great list of packages currently isolated in the image and a few people stepped forward. Let us simply delegate this task to one of the Guides to coordinate. Anyone up to it? Ned? Tim? That task is for starters to simply take that list and put names on the packages. The next step is how to do the stakeout in practice (Avi probably has ideas with PI etc).
I'd be willing to do it but I'm busy until the end of the month.
squeakfoundation@lists.squeakfoundation.org
-
Andreas Raab -
Avi Bryant -
Daniel Vainsencher -
Doug Way -
ducasse -
goran.krampe＠bluefish.se -
Ken Causey -
Marcus Denker -
Ned Konz