December 2009 - Pharo-dev - lists.pharo.org

Re: [Pharo-project] Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

by Stan Shepherd

StÃ©phane Ducasse wrote: > > my main message is > Just Do Something > take 10 min and do something easy > > Stan I would like to have already the first level of SmallLint ok > - bug > > After the problems is that we should annotate the methods or keep a data > structure somewhere > to flag the false positives. > > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > I have been 'overriding' the false positives with pragmas, as implemented by Lukas. Works well, although it would be good if they had a separate area so they don't become bigger than the code itself. ...Stan -- View this message in context: http://n2.nabble.com/Solving-the-documentation-problem-Capturing-tacit-know… Sent from the Pharo Smalltalk mailing list archive at Nabble.com.

Dec. 31, 2009

Re: [Pharo-project] Beginner question :) search and replace in String

by StÃ©phane Ducasse

+ 1 :) >>> > Please no, smalltalk is not awk or ruby and noone should expect that > these cryptic function names are well known. Message names should be > as descriptive as possible, this enables understanding the code without > documentation. Short message names have no advantage, we are not in the > 80's. > > > Levente > >> >> --AA >> >> >> >> _______________________________________________ >> Pharo-project mailing list >> Pharo-project(a)lists.gforge.inria.fr >> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project >> > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

Dec. 31, 2009

Re: [Pharo-project] Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

by Janko MivÅ¡ek

Adrian, that is exactly my idea too! That way the active newcommers like Sophie can easily help documenting the code by simply adding their notes, thoughts and suggestions in their own style, while in the next step someone more "professional", that is, more knowledgeable documenter can extract from this valuable contribution from fresh minds into the "official" code comments. Happy New Year for Pharo and to all Pharoers! JAnko On 31. 12. 2009 19:30, Adrian Lienhard wrote: > What about using a wiki to gather and edit comments (as suggested by > Stan) and then integrate them in a second step so that they are kept > together with the code (as suggested by Stef)? Just a thought... > > Cheers > Adrian > > On Dec 31, 2009, at 18:09 , StÃ©phane Ducasse wrote: > >> Stan >> >> My point is not to discourage you. :) >> Documentation is a state of mind and a large valuable job. >> Now we can do the same as you said (a guy ask and the others try to >> answer >> and we write comments that are pushed into the system). >> >> A first step is >> - make a list of the classes that are missing comments: >> - pick one a week and via the mailing-list make it better and after >> we integrate it. >> First it would be fun and we would get one class commented at the >> end of the week. >> >> Stef >> >> >>>> >>>> Stan >>>> >>>> Outsourcing documentation does not work. >>>> Having tests is one way but comments are crucial. >>>> You see we open issue to fix and add a single comment. >>>> >>>> The way to go is >>>> - having browsers showing doc all the times >>>> (like the old browser was showing the class def and the class >>>> comment) >>>> - defining better tools to browse documentation. >>>> I started (but did not finish) to use the new tree developed by >>>> alain to >>>> provide a package >>>> |> class >>>> class comment >>>> V method >>>> methodcomment >>>> method >>>> methodcomment >>>> |> class >>>> class comment >>>> |> methods >>>> |> class >>>> class comment >>>> |> methods >>>> >>>> We need a better version of >>>> ClassTree new openOn: Collection >>>> Stef >>>> >>>> >>> >>> >>> StÃ©phane Ducasse wrote: >>>> >>>> Outsourcing documentation does not work. >>>> >>> >>> True, in much the same way as: >>> >>> >>>> it has been said that democracy is the worst form of government >>>> except all >>>> those other forms that have been tried from time to >>>> time ...Winston >>>> Churchill >>>> >>> >>> In my image there are 905981methods without comments. Assuming 99% >>> are >>> trivial or self documenting, that would mean 9000 comments require >>> documentation. >>> >>> Given that the developers/maintainers have lived this long without >>> documenting these, what level of confidence would you have that >>> people will >>> go back and do so once you offer them the perfect documentation >>> tool? Given >>> a choice of building the next greatest thing, or sitting down to a >>> nice >>> session of documenting, ... >>> >>> On the other hand, you have users ( I think Sophie has been a good >>> example) >>> who work their way through things, ask the questions, get it >>> straight in >>> their own minds, then are happy to share what they have learnt. If >>> you have >>> spent 2 hours or 2 days puzzling something out, then spending >>> another 5 >>> minutes to capture that information for the sake of others is an >>> obvious >>> step. Also, the person using a piece of functionality knows what >>> they find >>> unclear; someone who has been using the software for 4 years would >>> have >>> remarkable insight to be able to put themselves into the place of >>> the new >>> user seeing the code for the first time. >>> >>> For similar reasons, tests are frequently not good documentation. >>> The test >>> writer wants the best way to test 50 similar cases with the least >>> code, so >>> writes some smart code around the tests to do all the setup etc in >>> generic >>> ways. The person seeking documentation wants a simple piece of code >>> to see a >>> function operate, without having to strip away levels of indirection, >>> boilerplate, attractive screen formatting,.... >>> >>> What would be the worst case if all users had a quick way to update >>> documentation? The guardians of a package would review their >>> watchlist once >>> a week, and revert or edit any incorrect documentation. Just the >>> fact of >>> someone trying and failing to explain a method could spur the >>> author to >>> provide a better explanation. >>> >>> A useful social contract would grow up, where the developer agrees >>> to answer >>> questions, and the questioner agrees to make the first cut at >>> documenting >>> the answer. There could be a change in the culture of doing without >>> documentation, and (I believe) a rapid improvement in the >>> completeness of >>> documentation. And imagine if the quality and completeness of the >>> documentation became a positive selling point for Pharo. >>> >>> As Mariano said about the release images, what a shame to build the >>> perfect >>> system but only a dozen people be able to use it. >>> >>> Thanks to all the contributors for your great work. Help us to help >>> you to >>> finish it to showroom standard. >>> >>> ...Stan -- Janko MivÅ¡ek AIDA/Web Smalltalk Web Application Server http://www.aidaweb.si

Dec. 31, 2009

Re: [Pharo-project] Beginner question :) search and replace in String

by Levente Uzonyi

On Thu, 31 Dec 2009, Adrian Kuhn wrote: > <csrabak@...> writes: > >> This brings to the forum an interesting debate! Clearly Levente's solution >> is the String redirection for Lukas' solution. >> >> Do this method eases programming for newcomers? Or it creates burden as >> presented in Stan's posting? >> >> AK is IIUC very knowledgeable of tools used in Squeak/Pharo and even though, >> had difficulty to find this >> particular method!! > > Good point! > > To replace parts of a string, I want to send a message to the string not to the > regex. So without doubt, string should understand such a messages. (I dont > know to which posting of Stan you're referring though). > > Also, I would expect short message names for common operations. Alas none of > > #copyWithRegex:matchesReplacedWith: > #asRegex + #copy:replacingMatchesWith: > #copyReplaceAll:with: > > is particular short. And to make things words, none of these shows up when auto > completing #repl... because they all start with copy. Plus strings are nested > in such a deep hierarchy that reading all understood messages won't scale. > > Personally, I would love to have a #gsub:with: on String. It is short and uses > established vocabulary. Please no, smalltalk is not awk or ruby and noone should expect that these cryptic function names are well known. Message names should be as descriptive as possible, this enables understanding the code without documentation. Short message names have no advantage, we are not in the 80's. Levente > > --AA > > > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project >

Dec. 31, 2009

Re: [Pharo-project] Beginner question :) search and replace in String

by Levente Uzonyi

On Thu, 31 Dec 2009, csrabak(a)bol.com.br wrote: > This brings to the forum an interesting debate! Clearly Levente's solution is the String redirection for Lukas' solution. > > Do this method eases programming for newcomers? Or it creates burden as presented in Stan's posting? Definitely, if you know how to search for methods. I was looking for a regex solution and found it in the *VB-regex category. > > AK is IIUC very knowledgeable of tools used in Squeak/Pharo and even though, had difficulty to find this particular method!! > MethodFinder is not up-to-date. Levente > my 0.019999... > > -- > Cesar Rabak > > > Em 31/12/2009 14:45, Levente Uzonyi <leves(a)elte.hu> escreveu: > > > On Thu, 31 Dec 2009, Lukas Renggli wrote: > >>> Anyway, the +10 bounty for a regex solution is still open! >> >> 'bar' asRegex copy: 'foobarqux' replacingMatchesWith: 'XYZ' > > Or: 'foobarqux' copyWithRegex: 'bar' matchesReplacedWith: 'XYZ' > > > Levente > >> >> Lukas >> >> -- >> Lukas Renggli >> http://www.lukas-renggli.ch >> >> _______________________________________________ >> Pharo-project mailing list >> Pharo-project(a)lists.gforge.inria.fr >> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project >> > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project >

Dec. 31, 2009

Re: [Pharo-project] Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

by StÃ©phane Ducasse

my main message is Just Do Something take 10 min and do something easy Stan I would like to have already the first level of SmallLint ok - bug After the problems is that we should annotate the methods or keep a data structure somewhere to flag the false positives.

Dec. 31, 2009

Re: [Pharo-project] Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

by Adrian Lienhard

What about using a wiki to gather and edit comments (as suggested by Stan) and then integrate them in a second step so that they are kept together with the code (as suggested by Stef)? Just a thought... Cheers Adrian On Dec 31, 2009, at 18:09 , StÃ©phane Ducasse wrote: > Stan > > My point is not to discourage you. :) > Documentation is a state of mind and a large valuable job. > Now we can do the same as you said (a guy ask and the others try to > answer > and we write comments that are pushed into the system). > > A first step is > - make a list of the classes that are missing comments: > - pick one a week and via the mailing-list make it better and after > we integrate it. > First it would be fun and we would get one class commented at the > end of the week. > > Stef > > >>> >>> Stan >>> >>> Outsourcing documentation does not work. >>> Having tests is one way but comments are crucial. >>> You see we open issue to fix and add a single comment. >>> >>> The way to go is >>> - having browsers showing doc all the times >>> (like the old browser was showing the class def and the class >>> comment) >>> - defining better tools to browse documentation. >>> I started (but did not finish) to use the new tree developed by >>> alain to >>> provide a package >>> |> class >>> class comment >>> V method >>> methodcomment >>> method >>> methodcomment >>> |> class >>> class comment >>> |> methods >>> |> class >>> class comment >>> |> methods >>> >>> We need a better version of >>> ClassTree new openOn: Collection >>> Stef >>> >>> >> >> >> StÃ©phane Ducasse wrote: >>> >>> Outsourcing documentation does not work. >>> >> >> True, in much the same way as: >> >> >>> it has been said that democracy is the worst form of government >>> except all >>> those other forms that have been tried from time to >>> time ...Winston >>> Churchill >>> >> >> In my image there are 905981methods without comments. Assuming 99% >> are >> trivial or self documenting, that would mean 9000 comments require >> documentation. >> >> Given that the developers/maintainers have lived this long without >> documenting these, what level of confidence would you have that >> people will >> go back and do so once you offer them the perfect documentation >> tool? Given >> a choice of building the next greatest thing, or sitting down to a >> nice >> session of documenting, ... >> >> On the other hand, you have users ( I think Sophie has been a good >> example) >> who work their way through things, ask the questions, get it >> straight in >> their own minds, then are happy to share what they have learnt. If >> you have >> spent 2 hours or 2 days puzzling something out, then spending >> another 5 >> minutes to capture that information for the sake of others is an >> obvious >> step. Also, the person using a piece of functionality knows what >> they find >> unclear; someone who has been using the software for 4 years would >> have >> remarkable insight to be able to put themselves into the place of >> the new >> user seeing the code for the first time. >> >> For similar reasons, tests are frequently not good documentation. >> The test >> writer wants the best way to test 50 similar cases with the least >> code, so >> writes some smart code around the tests to do all the setup etc in >> generic >> ways. The person seeking documentation wants a simple piece of code >> to see a >> function operate, without having to strip away levels of indirection, >> boilerplate, attractive screen formatting,.... >> >> What would be the worst case if all users had a quick way to update >> documentation? The guardians of a package would review their >> watchlist once >> a week, and revert or edit any incorrect documentation. Just the >> fact of >> someone trying and failing to explain a method could spur the >> author to >> provide a better explanation. >> >> A useful social contract would grow up, where the developer agrees >> to answer >> questions, and the questioner agrees to make the first cut at >> documenting >> the answer. There could be a change in the culture of doing without >> documentation, and (I believe) a rapid improvement in the >> completeness of >> documentation. And imagine if the quality and completeness of the >> documentation became a positive selling point for Pharo. >> >> As Mariano said about the release images, what a shame to build the >> perfect >> system but only a dozen people be able to use it. >> >> Thanks to all the contributors for your great work. Help us to help >> you to >> finish it to showroom standard. >> >> ...Stan >> >> >> >> >> >> >> >> >> >> >> -- >> View this message in context: http://n2.nabble.com/Solving-the-documentation-problem-Capturing-tacit-know… >> Sent from the Pharo Smalltalk mailing list archive at Nabble.com. >> >> _______________________________________________ >> Pharo-project mailing list >> Pharo-project(a)lists.gforge.inria.fr >> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

Dec. 31, 2009

Re: [Pharo-project] Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse.

by Stan Shepherd

csrabak wrote: > > > > > Em 31/12/2009 15:09, StÃ©phane Ducasse < stephane.ducasse(a)inria.fr > > escreveu: > >> Stan > >> My point is not to discourage you. :) Documentation is a state of >> mind and a large valuable job. Now we can do the same as you said >> (a guy ask and the others try to answer and we write comments that >> are pushed into the system). > >> A first step is >> - make a list of the classes that are missing comments: > > +--------+-------+-------+ > | Image | update|missing| > | | |comment| > +--------+-------+-------+ > |1.0-dev | 10502 | 1831 | > +--------+-------+-------+ > |1.1-core| 11098 | 703 | > +--------+-------+-------+ > | 1.1-dev| 11098 | 1795 | > +--------+-------+-------+ > > >> - pick one aweek and via the mailing-list make it better and after >> - we integrate it. > >> First it would be fun and we would get one class commented at the >> end of the week. > > HTH > > -- > Cesar Rabak > for info, I ran code critics on Lukas's quasi-release http://www.seaside.st/distributions/Seaside-3.0a5.app.zip which is essentially web dev without O2 I believe. (Code critics I can't get to work in web dev) Taking out spelling, there are about 30000 items flagged, of which 4802 long methods. In an ideal world, it would be nice if the whole image passed code critics. > - pick one aweek and via the mailing-list make it better and after > - we integrate it. Well the one that's entertaining me at the moment is JSObject, but I imagine people would rather start with a core class?. ...Stan -- View this message in context: http://n2.nabble.com/Solving-the-documentation-problem-Capturing-tacit-know… Sent from the Pharo Smalltalk mailing list archive at Nabble.com.

Dec. 31, 2009

Re: [Pharo-project] Beginner question :) search and replace in String

by Adrian Kuhn

<csrabak@...> writes: > This brings to the forum an interesting debate! Clearly Levente's solution > is the String redirection for Lukas' solution. > > Do this method eases programming for newcomers? Or it creates burden as > presented in Stan's posting? > > AK is IIUC very knowledgeable of tools used in Squeak/Pharo and even though, > had difficulty to find this > particular method!! Good point! To replace parts of a string, I want to send a message to the string not to the regex. So without doubt, string should understand such a messages. (I dont know to which posting of Stan you're referring though). Also, I would expect short message names for common operations. Alas none of #copyWithRegex:matchesReplacedWith: #asRegex + #copy:replacingMatchesWith: #copyReplaceAll:with: is particular short. And to make things words, none of these shows up when auto completing #repl... because they all start with copy. Plus strings are nested in such a deep hierarchy that reading all understood messages won't scale. Personally, I would love to have a #gsub:with: on String. It is short and uses established vocabulary. --AA

Dec. 31, 2009

Re: [Pharo-project] Can't debug in 1.1

by Martin McClure

Henrik Sperre Johansen wrote: > The MapCache is not registered for finalization, IIRC. > The new WeakKeyDictionary does not work reliably without being registered. > See also http://code.google.com/p/pharo/issues/detail?id=1628. > I remember wanting to retract some parts of comment #2 after further > investigation, but I no longer remember which :) > Should give some pointers though. I *think* it's OK for MapCache to not be registered, because before each potential add or remove, DebuggerMethodMap sends #finalizeValues to it. And I also had some doubts about the code described in issue 1628, but I don't see how it could have caused this particular corruption, where the array is all nils yet tally is > 0. Regards, -Martin

Dec. 31, 2009