January 2010 - Pharo-dev - lists.pharo.org

Re: [Pharo-project] FontChooser open -> DNU

by Adrian Lienhard

It seems you cannot open a FontChooser like this because it expects a setSelector, getSelector, and a receiver. See for instance the call in the method #chooseCodeFont. If called by FontChooser class>>open, some code fails that expects these selectors and receiver being initialized. So maybe we should just delete #open?! Cheers, Adrian On Jan 1, 2010, at 18:14 , StÃ©phane Ducasse wrote: > Hi guys > > Apparently FontChooser open raise an error > > http://code.google.com/p/pharo/issues/list?thanks=1728 > > Stef > > > > > _______________________________________________ > Pharo-project mailing list > Pharo-project(a)lists.gforge.inria.fr > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

Jan. 1, 2010

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

by StÃ©phane Ducasse

11131 ----- - Added Class comments to FontChooser and FontChooserMorph Reorganized the class categories. Remove the as yet unclassified categories. I'm quite that a lot of it requires a little amount of energy from each of us. Stef

Jan. 1, 2010

[Pharo-project] FontChooser open -> DNU

by StÃ©phane Ducasse

Hi guys Apparently FontChooser open raise an error http://code.google.com/p/pharo/issues/list?thanks=1728 Stef

Jan. 1, 2010

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

by Adrian Lienhard

On Jan 1, 2010, at 14:16 , Stephan Eggermont wrote: > Adrian 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... > > I'd very much prefer an in-image solution and avoid > integrating. What I suggested is an in-image solution, just that the contribution is done via a wiki from which the text is then integrated (i.e., copied or even moved). The alternative would be that people directly write comments in a Pharo image and then commit changes to the inbox. The wiki may work out better because it is simpler to add and edit contributions. Either way you need to integrate. Somehow the changes need to get into the PharoCore and we want to have review what gets in. > In-image we have much better version > info, and much better browsing available. Yes. As Lukas pointed out in another mail, one major difficulty is to get contributions. Unless we have a few people that regularly commit time to writing and reviewing comments, we won't make progress... Cheers, Adrian

Jan. 1, 2010

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

by Stephan Eggermont

Adrian 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... I'd very much prefer an in-image solution and avoid integrating. In-image we have much better version info, and much better browsing available. Stephan

Jan. 1, 2010

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

by Lukas Renggli

>From my experience with Seaside I can only give these (rather pessimistic) comments: - In Seaside we have the policy that every public class and every public method is commented. We are not there yet with all the code, but we have a few packages that have 100% comment coverage. The disappointing thing is that there are still questions where we can point the reader to the method or simply copy and paste the method comment in question. People don't read comments, even if they are at their finger-tips. I think that even less people would read them when they were in a web-browser. - We've been asking people to help with class comments for many years already, but the contributions have been minor. A few people pointed out spelling errors and one person contributed some class comments. Another problem is that outsiders often do not have the knowledge to write class comments, after all they are the target audience. Users of the code don't have the time to write a comment. They want to get their code running after figuring out how it works. This is only the developer that writes them, if anybody. - Separating documentation from code doesn't work. Early versions of Seaside had part of the documentation externalized in Wikis. This documentation quickly out-dates and potentially misguides readers with wrong information for many years. Also have a look at how other open source projects dealt with this in the past. PrototypeJS and script.aculo.us has a wiki for many years: I think they lost popularity mostly because they could not keep the documentation and examples accurate and in sync with the code. They fixed that now and create accurate documentation from the code. Lukas -- Lukas Renggli http://www.lukas-renggli.ch

Jan. 1, 2010

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

by Schwab,Wilhelm K

Fair enough, but PBE is well on its way to being good enough that people will refer to it early and often. The day might come when things will be found in its index rather than a search engine. Speaking of that, how about an html copy of PBE's index (or even the entire book) on the web??? I prefer the PDF for most things, but web-hosted html would cover the search engine users. Bill -----Original Message----- From: pharo-project-bounces(a)lists.gforge.inria.fr [mailto:pharo-project-bounces@lists.gforge.inria.fr] On Behalf Of Adrian Kuhn Sent: Friday, January 01, 2010 12:47 AM To: pharo-project(a)lists.gforge.inria.fr Subject: Re: [Pharo-project] Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse. Schwab,Wilhelm K <bschwab@...> writes: > This sounds like a great way to augment documentation, but I still > like class and method comments - Stef might want to work on the train > :) Various things mentioned here recently (such as threading) will > hopefully get chapters in PBE. My (general) problem with book chapters is that they are not googlable. For example the awesome chapter on how exceptions work that was sent around on this list some time ago. Nobody will *ever* gonna stumble upon that chapter when googling (or binging, et cetera) for "exceptions smalltalk". OTOH, when I write a blog post it is indexed within 2 minutes! --AA _______________________________________________ Pharo-project mailing list Pharo-project(a)lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

Jan. 1, 2010

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

by Adrian Kuhn

Schwab,Wilhelm K <bschwab@...> writes: > This sounds like a great way to augment documentation, but I still like class > and method comments - Stef might want to work on the train :) Various things > mentioned here recently (such as threading) will hopefully get chapters in > PBE. My (general) problem with book chapters is that they are not googlable. For example the awesome chapter on how exceptions work that was sent around on this list some time ago. Nobody will *ever* gonna stumble upon that chapter when googling (or binging, et cetera) for "exceptions smalltalk". OTOH, when I write a blog post it is indexed within 2 minutes! --AA

Jan. 1, 2010

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

by Schwab,Wilhelm K

This sounds like a great way to augment documentation, but I still like class and method comments - Stef might want to work on the train :) Various things mentioned here recently (such as threading) will hopefully get chapters in PBE. Bill -----Original Message----- From: pharo-project-bounces(a)lists.gforge.inria.fr [mailto:pharo-project-bounces@lists.gforge.inria.fr] On Behalf Of Adrian Kuhn Sent: Thursday, December 31, 2009 10:17 PM To: pharo-project(a)lists.gforge.inria.fr Subject: Re: [Pharo-project] Solving the documentation problem. Capturing tacit knowledge. Knowledge reuse. Adrian Lienhard <adi@...> writes: > 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... That gave me an idea, what about structuring that wiki like the discussion pages of wikipedia? That is, the wiki is structured by classes and methods, and in the image the browser shows a [wiki] button for classes and methods everywhere. This decouples publishing of code (functional contributions that you want to have double checked and tested by a core member) from publishing of comments (where like on wikipedia everyone can contribute without much harm). Also no dull work required to review and brush up all the information. Of course, initial effort is setting up a wiki with URLs of form /wiki/classname/methodname and including a button in OB that opens the wiki. --AA _______________________________________________ Pharo-project mailing list Pharo-project(a)lists.gforge.inria.fr http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project

Jan. 1, 2010

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

by Adrian Kuhn

Levente Uzonyi <leves@...> writes: > > 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. I dare to disagree :) Growing a language *and* compressing it. There is two directions for natural growth of a language. Composing complex expressions from simple ones (see Guy Steele's classic OOPSLA keynote) *and* shortening the name of often the most common operations. The latter is clearly something that should happen overtime as an evolutionary process and not up front. Akira Tanaka refers to this as the "huffman coding" of API design. I have written about that on my blog [1]. So method names should initially be as descriptive as possible, but often used method names should get a short alias. In 80 when Smalltalk was fresh, #copyReplaceAll:with: was a revolutionary short "huffman encoding" for like 20 lines of C (or worse) code. Smalltalk was visionary in using long method names in the 80ies, but to each anti-thesis there is a synthesis. Today we are 30 years later, and "gsub" has established itself as a generally known name for replacing all occurrences of a pattern in a string. IMHO it has evolved from what once used to be a cryptic function name to a proper programming term of its own. We can think of other mebbe more Smalltalkesque huffman codings also, eg 'foobarqux' at: 'bar' put: 'XYZ'. with a double dispatch on the parameter of the #at: keyword, this would even open up the API of String for unlimited extensions by clients without cluttering it with dozens of new messages. So you could use integers, strings, regeces, et cetera... Well, just brainstorming :) --AA [1]: http://www.iam.unibe.ch/~akuhn/blog/2009/one-letter-method-names/

Jan. 1, 2010