[squeak-dev] [Documentation] Classes with class comment with size > 1000 chars

Hannes Hirzel hannes.hirzel at gmail.com
Sun May 2 20:27:06 UTC 2010


Smalltalk allClasses size

2071


(Smalltalk allClasses reject: [ :class |
class inheritsFrom: TestCase ]) size

1797


((Smalltalk allClasses reject: [ :class |
class inheritsFrom: TestCase ])
select: [ :class |
	class organization classComment = ''  ]) size

660


Another interesting question: What are the results regarding Collections only?

--Hannes

On 5/2/10, Casey Ransberger <casey.obrien.r at gmail.com> wrote:
> I'd actually recommend that we worry about documenting the tests after
> documenting the classes they test for several reasons.
>
>  - Tests are a form of documentation already. When I am looking for ways to
> use a class, and the class comment is insufficient, I'll often look at
> whatever tests are available.
>
>  - I would rather focus on the core classes that one needs to use all the
> time first, and work our way out from there.
>
>  - The way you use the tests, for most folks anyway, is to use the test
> runner. While I can recall having run the tests without it once, I'd call
> that a use case for intermediate users. We still have a big fat question
> mark button in classes beginners will need to use, which leads them to a box
> that says "class has no comment" and I think we should deal with that
> *first.*
>
> Then again, this is just how Casey's internal triage works. I am known for
> punting things when I see something that brains me as more important. Your
> spiritual mileage may of course vary!
>
> Anyhow, it would be lovely if other folks interested might sanity check this
> expression as successfully excluding the tests:
>
> (Smalltalk allClasses reject: [ :class |
> class inheritsFrom: TestCase ])
>
> On Sun, May 2, 2010 at 12:39 PM, Michael Haupt <mhaupt at gmail.com> wrote:
>
>> Hi Hannes,
>>
>> On Sun, May 2, 2010 at 9:32 PM, Hannes Hirzel <hannes.hirzel at gmail.com>
>> wrote:
>> >> So, of 2033 classes in the image, 814 have no class comment *at all*.
>> >> That's 40 %, and *that* is a shame.
>> >
>> > Or put it otherwise 60% have a comment. A good point to start .....  :-)
>>
>> I'm glad to see someone is accepting the optimist hat. :-)
>>
>> > The test classes are there to test the corresponding class. I think we
>> > can safely say they do not need a comment at this time. How can we
>> > exclude them from the metrics?
>>
>> I'd rather not do that - test classes may have certain characteristics
>> in what they target, and how. It may be *very* interesting to know
>> details about these things.
>>
>> >> A dictionary is not sorted by default. Or is it?
>> >
>> > So I wonder, where is the Collection with keys and values where the
>> > keys are sorted?
>>
>> I'm afraid I don't understand - Dictionary uses hashing internally.
>> There is no sorted collection of keys in there. In case you mean to
>> ask whether there is any Collection that does this, I'm afraid there
>> is none (but that's me talking).
>>
>> Best,
>>
>> Michael
>>
>>
>
>
> --
> Casey Ransberger
>



More information about the Squeak-dev mailing list