Effective SM entries (was Proposal for Morphicperformance-measurement enhancement)

Roel Wuyts wuyts at iam.unibe.ch
Wed Jul 30 07:41:16 UTC 2003


Fully agreed.

You definitely see people use all kinds of different styles of 
documentation (yesterday I looked at some code that provides example 
methods on the class side, lately I use unit tests for most of my 
documentation, some people favor class comments, other ones put 
everything in methods that contain no code but only comments, yet other 
ones rely on the SAR format that spawns a workspace with comments). I 
have to look at a lot of existing code, and I always have to do all 
these magical incantations to find a scrap of information (if any). 
Every time I want to write a comment I have to think: where will I put 
it this time? Does it feel like a class comment? An example method 
maybe? Or no, let;s put it on a method in the 'documentation' 
protocol...

<globe of invulnerability> (*)
So why don't we put comments in code annotations, so that
- it is clear for the developer where to put them: put them in the 
annotation where the comment is relevant. For example, annotate an 
instance variable with whatever you like. Or annotate a method, a 
class, ...
- it is clear for the user where to look
- (new) it is possible (and quite easy even) to write a documentation 
browser (or integrate this in the standard browser). So in one glance 
you could have all comments associated with a certain class, for 
example.
</globe of invulnerability>


(*) Have been playing some Neverwinter Nights lately, a dungeon&dragons 
role-playing game :-) I'd love to have their circular pop-up menus in 
Squeak. Maybe somebody can have some fun implementing them for Squeak 
:-) They allow a lot of muscle memory in a short space, which makes 
them easy to use.


On Wednesday, Jul 30, 2003, at 08:43 Europe/Zurich, Andreas Raab wrote:

> David,
>
> Let rephrase what I am trying to achive here: I am not interested in 
> where
> to put documentation (I don't care) but I am rather interested in HOW 
> TO GET
> TO IT.
>
> All of what you propose has its merits and all of what you propose has 
> been
> done. There are classes which contain documentation (such as
> AGenieIntroduction) there are categories which contain documentation 
> (such
> as in BalloonEngineBase class) there are methods containing 
> documentation
> (browse the implementors of #aComment) but that doesn't mean it's 
> accessible
> for people, that people know where to go looking for it.
>
> What I want is a simple mechanism that people to hook up their 
> documentation
> right in the UI so that there is a simple, obvious way to provide 
> varying
> bits and pieces of information without requiring the user to "guess 
> right"
> at what the magic incantation is that will bring up the bit of 
> information
> which they are so urgently looking for.
>
> So "simple" means really "simple to FIND by the user, and simple to 
> USE by
> the programmer". And while all of what you propose is certainly simple 
> to
> use, practice shows that it is typically not simple to find.
>
> Cheers,
>   - Andreas
>
>> -----Original Message-----
>> From: squeak-dev-bounces at lists.squeakfoundation.org
>> [mailto:squeak-dev-bounces at lists.squeakfoundation.org] On
>> Behalf Of David T. Lewis
>> Sent: Wednesday, July 30, 2003 4:23 AM
>> To: The general-purpose Squeak developers list
>> Subject: Re: Effective SM entries (was Proposal for
>> Morphicperformance-measurement enhancement)
>>
>>
>> On Tue, Jul 29, 2003 at 08:39:49PM +0200, Andreas Raab wrote:
>>>> Rather than making yet another image-based registry, I think this
>>>> would be a great use for the "annotations" that are part of the
>>>> SMCard. After all, we *do* have a master registry for SM packages
>>>> already.
>>>
>>> Fine with me, I was just shooting for the simplest thing
>> that could possibly
>>> work ;-) Considering that we have
>> WorldMenu>>registerOpenCommand: it seemed
>>> to me that having WoldMenu>>registerPackageCommand: might
>> just be the
>>> simplest solution of all.
>>
>> Well, if we just need something simple that works, how about:
>>
>> 1) Class comments, at least for one or more classes that are obviously
>> associated with the SM package in question.
>>
>> 2) An agreed naming convention for a class side method
>> category such as,
>> well, "documentation". This would be a place to put documentation.
>>
>> 3) An agreed naming convention for methods that provide documentation,
>> such as MyClass class>>squeakMapPackageInfo.
>>
>> The default implemention of squeakMapPackageInfo could be:
>>
>> Object class>>squeakMapPackageInfo
>>   ^ self comment
>>
>> Anyone who does not bother with class comments would get a suitably
>> embarrassing "comment template" on SM. By writing at least one class
>> comment, a slightly less embarrassing message would be
>> displayed on SM.
>> And anyone with sufficient motivation to provide actual documentation
>> could do so by hooking something useful into a #squeakMapPackageInfo
>> method.
>>
>> I'm assuming that most SM entries will include some class that is
>> an obvious place to keep the documentation, and that we could invent
>> some simple way to associate the squeakMapPackageInfo for that class
>> with the SM package and make it available to Squeak Map browsers of
>> various sorts.
>>
>> This would be practically zero extra work for anybody who documents
>> their classes. And I'm betting that someone who can't be bothered with
>> class comments is not likely to spend a lot of time updating
>> Yet Another
>> High Tech Documentation Tool that is maintained separately from their
>> code base. I for one wouldn't do it.
>>
>> Dave
>>
>>
>
>
>
Roel Wuyts                                                   Software 
Composition Group
roel.wuyts at iam.unibe.ch                       University of Bern, 
Switzerland
http://www.iam.unibe.ch/~wuyts/
Board Member of the European Smalltalk User Group: www.esug.org



More information about the Squeak-dev mailing list