April 2011 - Pharo-dev - lists.pharo.org

Re: [Pharo-project] What is a well documented class?

by Michael Forster

On Sat, Apr 23, 2011 at 10:13 PM, Alexandre Bergel <alexandre.bergel(a)me.com> wrote: [...] > Â - each public method belongs to a method category named public* > Â - each private method belongs to a method category named private* Others here may disagree -- and the dreary of legislating and enforcing conventions aside -- but I strive (usually with success) to move all privately-used methods to one or more delegates. One class's private method is just another's public??? > Â - other methods are considered as "package visible", meaning that they belong to a category that does not begins with 'private' or 'public' Again, I sympathise with facing the visibility problem, but I don't trust that conventions will be upheld by either end, so I tire of following them. Replace Pharo/Squeak categories with Newspeak modules; replace Pharo/Squeak protocols with traits (stateless, please); I'll be the first in line. My 0.25 :-) Mike

April 24, 2011

Re: [Pharo-project] What is a well documented class?

by Michael Forster

On Sun, Apr 24, 2011 at 4:03 AM, StÃ©phane Ducasse <stephane.ducasse(a)inria.fr> wrote: > for the class comment I would have > > intention > Â Â Â Â I'm doing that > collaborations > Â Â Â Â with the help of this class and that class > main api > Â Â Â Â my main public API is ... > > Â Â Â Â my subclasses may want to override such specific hooks ... Yes, yes! I would like to see those suggestions used by the default comment template for new classes. > Implementation notes > Â Â Â Â iv and their purposes May I ask, what if we stopped ever mentioning instance vars in the class comment? Perhaps it's a problem of having only one place to document both external and internal details of the class, but it really irks me when the comment template for a newly created class suggests that I divulge the implementation details in what appears to be a document of the interface. Moreover, the comment must change when the implementation changes, even if the interface remains the same. Perhaps that's why so many class comments seem out of sync with the current state of their classes. Thoughts? Mike

April 24, 2011

Re: [Pharo-project] What is a well documented class?

by Mariano Martinez Peck

On Sun, Apr 24, 2011 at 5:13 AM, Alexandre Bergel <alexandre.bergel(a)me.com>wrote: > Hi! > > I am dreaming about a tool to help me document source code. The question I > have is what is a well documented class? > What do you think about the following: > > A well documented class is a class: > - that contains a class comment > - its class comments contains either an example, or an associated unit > test > yes but sometimes the mapping is not "one to one" between classes and methods > - without 'as yet unclassified' method category > - each public method belongs to a method category named public* > For me no. that's just a convention you may use. I don't put all my public methods in public* > - each private method belongs to a method category named private* > the same here..sometimes in put them in private* but soemtimes no. > - each method contains a comment, located before the declaration of > temporary variables > It depends if it is worth it or not. Putting a comment that explains exactly the same than the code is not worth it if the method is "self explanatory". Anyway, millions of times you do need to put comments and they help. > - other methods are considered as "package visible", meaning that they > belong to a category that does not begins with 'private' or 'public' > this sounds too java for me. > - without commented code contained in its methods. > > Is there anything else? > > For me, when dealing with frameworks where there are "base" clases that one can subclass and make its own concrete subclass, it is NEVER documented which methods should I implement. What I mean is that I really like (and I do it) to create a superclass with all the necessary methods as ^ self subclassResponsability (yes, kind of Java interface). cheers mariano > Cheers, > Alexandre > -- > _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: > Alexandre Bergel http://www.bergel.eu > ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;. > > > > > > > -- Mariano http://marianopeck.wordpress.com

April 24, 2011

Re: [Pharo-project] About testing that ensure works

by StÃ©phane Ducasse

Ok I got it I ws confused by SUnit interference testDo "self run: #testDo" self do: [ Error signal]. self assert: x = 3 self run: #testDo -> red tests self debug: #testDo + proceed -> green tests

April 24, 2011

Re: [Pharo-project] About testing that ensure works

by StÃ©phane Ducasse

How can I ensure that really in case of error or not a piece of code is executed. Now I'm totally confused by the semantics of ensure: So I wrote that: testOnDo "self run: #testOnDo " self doOnDo: [ self error]. self assert: x = 3. x := 77. self doOnDo: [x = 21]. self assert: x = 3 ensure x := 3 doOnDo: aBlock x := 5. [aBlock value. self ensure] on: Error do: [:ex | self ensure].

April 24, 2011

Re: [Pharo-project] About testing that ensure works

by StÃ©phane Ducasse

I read what I wrote on the exception chapter and also the comments of the ensure: method and I do not get why >> > error are not causing ensure block to trigger. > only after you either abandon or proceed, an ensure block will be executed. to me it completely defeats the purpose of ensure: or ifCurtailed: Evaluate a termination block after evaluating the receiver, regardless of whether the receiver's evaluation completes. So when should ensure: be used? if I get an error because of a file problem will it be triggered? I do not see how this is working in that case Stef

April 24, 2011

Re: [Pharo-project] About testing that ensure works

by StÃ©phane Ducasse

On Apr 24, 2011, at 12:43 PM, Igor Stasenko wrote: > On 24 April 2011 13:26, StÃ©phane Ducasse <stephane.ducasse(a)inria.fr> wrote: >> here is a simpler case >> >> do: aBlock >> >> x := 5. >> [aBlock value] ensure: [x :=3] >> >> testDo >> "self run: #testDo" >> >> self do: [ self error]. >> self assert: x = 3 >> >> >> and I do not understand why ensure is not executed :( >> because I always want the ensure to happen not only on ifCurtailed: >> > > error are not causing ensure block to trigger. so what is causing them to trigger. I always thought ensure: was really giving that warranty. So this is really scary to me. I wrote that and this is green. testDo2 "self run: #testDo2 1 run, 1 passes, 0 expected failures, 0 failures, 0 errors, 0 unexpected passes" [self do: [ self error] ] on: Error do: [:ex | ]. self assert: x = 3. To me it means that I should not use ensure because it makes no sense to wrap the withOrganizer in a on: do: block outside. So I do not see the real use of ensure: Shit..... Stef > only after you either abandon or proceed, an ensure block will be executed. > > >> Stef >> > > -- > Best regards, > Igor Stasenko AKA sig. >

April 24, 2011

Re: [Pharo-project] is there a way to know whether an object is registered to an announcer?

by Igor Stasenko

On 24 April 2011 13:16, StÃ©phane Ducasse <stephane.ducasse(a)inria.fr> wrote: > weak > Â Â Â Â "announcer weak subscribe: foo" > Â Â Â Â ^ WeakSubscriptionBuilder on: self > > What could be the comment? > answer a receiver's proxy which can be used for subscribing using weak subscriptions. > Stef > > -- Best regards, Igor Stasenko AKA sig.

April 24, 2011

Re: [Pharo-project] About testing that ensure works

by Igor Stasenko

On 24 April 2011 13:26, StÃ©phane Ducasse <stephane.ducasse(a)inria.fr> wrote: > here is a simpler case > > do: aBlock > > Â Â Â Â x := 5. > Â Â Â Â [aBlock value] Â ensure: [x :=3] > > testDo > Â Â Â Â "self run: #testDo" > > Â Â Â Â self do: [ self error]. > Â Â Â Â self assert: x = 3 > > > and I do not understand why ensure is not executed :( > because I always want the ensure to happen not only on ifCurtailed: > error are not causing ensure block to trigger. only after you either abandon or proceed, an ensure block will be executed. > Stef > -- Best regards, Igor Stasenko AKA sig.

April 24, 2011

Re: [Pharo-project] About testing that ensure works

by StÃ©phane Ducasse

here is a simpler case do: aBlock x := 5. [aBlock value] ensure: [x :=3] testDo "self run: #testDo" self do: [ self error]. self assert: x = 3 and I do not understand why ensure is not executed :( because I always want the ensure to happen not only on ifCurtailed: Stef

April 24, 2011