[Documentation] Classes with class comment with size > 1000 chars
Locked
[Documentation] Classes with class comment with size > 1000 chars
 
|
Hello
The following gives all the classes which have a comment which is longer than 1000 chars. | s d | s := (Object selectSubclasses: [:cl | cl comment size > 1000]) asSortedCollection: [ :a :b | a name < b name]. d := Dictionary new. s do: [ :cl | d at: cl name put: cl comment]. d inspect I get 258 in an updated Trunk image. However I get every two times, e.g. once as #Base64MimeConverter Base64MimeConverter class So in fact there are only 129 with a class comment longer than 1000 chars. Questions: 1) How do I get them only once? 2) How do I get them sorted in the dictionary? Regards Hannes P.S. If I reduce the size of the comment to 600 chars at minimum I get around 250 classes. Other queries to asks could be: The number of classes which have more than e.g 40 methods and have a class comment which is shorter than 200 chars. |
Re: [Documentation] Classes with class comment with size > 1000 chars
|
|
Hi Hannes,
On Sun, May 2, 2010 at 9:10 PM, Hannes Hirzel <[hidden email]> wrote: > The following gives all the classes which have a comment which is > longer than 1000 chars. ah. You're on this too. Good. :-) Some metrics that I find interesting are these: [ Smalltalk allClasses size ] - that would be 2033 in my Trunk image. [ Smalltalk allClasses select: [ :class | class organization classComment = '' ] ] - this gives me an Array with 814 entries. So, of 2033 classes in the image, 814 have no class comment *at all*. That's 40 %, and *that* is a shame. In the inspector of the Array I got from above, [ self collect: [ :class | class category ] into: Set new ] gives me all the categories where the undocumented classes reside. There are many Kernel-* categories on that list, and also many *-Tests ones. (Just a quick glimpse.) > Questions: > 1) How do I get them only once? This: [ Smalltalk allClasses select: [ :class | class organization classComment size > 1000] ] gives me 130 (just updated my Trunk image). > 2) How do I get them sorted in the dictionary? A dictionary is not sorted by default. Or is it? Best, Michael |
Re: [Documentation] Classes with class comment with size > 1000 chars
|
|
Hi again,
On Sun, May 2, 2010 at 9:23 PM, Michael Haupt <[hidden email]> wrote: >> Questions: >> 1) How do I get them only once? > > This: > > [ Smalltalk allClasses select: [ :class | class organization > classComment size > 1000] ] > > gives me 130 (just updated my Trunk image). > >> 2) How do I get them sorted in the dictionary? > > A dictionary is not sorted by default. Or is it? eh, for some reason, the Array that the above code gives me is sorted by class name already. Nice. :-) I just saw in SystemDictionary that #classNames returns a SortedCollection in any case. Even nicer. :-) So, a dictionary probably won't help, but what about an Array with Associations? [ Smalltalk allClasses select: [ :class | class organization classComment size > 1000 ] thenCollect: [ :class | class -> class organization classComment ] ] Best, Michael |
Re: [Documentation] Classes with class comment with size > 1000 chars
|
|
In reply to this post by Michael Haupt-3
Hello Michael
The metrics are interesting. On 5/2/10, Michael Haupt <[hidden email]> wrote: > Hi Hannes, > > On Sun, May 2, 2010 at 9:10 PM, Hannes Hirzel <[hidden email]> > wrote: >> The following gives all the classes which have a comment which is >> longer than 1000 chars. > > ah. You're on this too. Good. :-) > > Some metrics that I find interesting are these: > > [ Smalltalk allClasses size ] - that would be 2033 in my Trunk image. > > [ Smalltalk allClasses select: [ :class | > class organization classComment = '' ] ] - this gives me an Array > with 814 entries. > > 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 ..... :-) > In the inspector of the Array I got from above, > > [ self collect: [ :class | class category ] into: Set new ] > > gives me all the categories where the undocumented classes reside. > There are many Kernel-* categories on that list, and also many *-Tests > ones. (Just a quick glimpse.) 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? >> Questions: >> 1) How do I get them only once? > > This: > > [ Smalltalk allClasses select: [ :class | class organization > classComment size > 1000] ] > > gives me 130 (just updated my Trunk image). Thank you. I did not remember this message anymore and that I have to go through the class organization. >> 2) How do I get them sorted in the dictionary? > > 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? Best wishes Hannes |
Re: [Documentation] Classes with class comment with size > 1000 chars
|
|
The last mail is my answer to Michael's first mail.
On 5/2/10, Hannes Hirzel <[hidden email]> wrote: > Hello Michael > > The metrics are interesting. > > On 5/2/10, Michael Haupt <[hidden email]> wrote: >> Hi Hannes, >> >> On Sun, May 2, 2010 at 9:10 PM, Hannes Hirzel <[hidden email]> >> wrote: >>> The following gives all the classes which have a comment which is >>> longer than 1000 chars. >> >> ah. You're on this too. Good. :-) >> >> Some metrics that I find interesting are these: >> >> [ Smalltalk allClasses size ] - that would be 2033 in my Trunk image. >> >> [ Smalltalk allClasses select: [ :class | >> class organization classComment = '' ] ] - this gives me an Array >> with 814 entries. >> >> 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 ..... :-) > >> In the inspector of the Array I got from above, >> >> [ self collect: [ :class | class category ] into: Set new ] >> >> gives me all the categories where the undocumented classes reside. >> There are many Kernel-* categories on that list, and also many *-Tests >> ones. (Just a quick glimpse.) > > 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? > > >>> Questions: >>> 1) How do I get them only once? >> >> This: >> >> [ Smalltalk allClasses select: [ :class | class organization >> classComment size > 1000] ] >> >> gives me 130 (just updated my Trunk image). > > Thank you. I did not remember this message anymore and that I have to > go through the class organization. > >>> 2) How do I get them sorted in the dictionary? >> >> 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? > > Best wishes > > Hannes > |
Re: [Documentation] Classes with class comment with size > 1000 chars
|
|
In reply to this post by Hannes Hirzel
Hi Hannes,
On Sun, May 2, 2010 at 9:32 PM, Hannes Hirzel <[hidden email]> 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 |
Re: [Documentation] Classes with class comment with size > 1000 chars
|
|
Regarding test cases, I agree. But I would put that as second priority.
If a Dictionary is a hash, yes, then there are no sorted keys. But what is then the difference to the superclass #HashedCollection. The comment of class dictionary: I represent a set of elements that can be viewed from one of two perspectives: a set of associations, or a container of values that are externally named where the name can be any object that responds to =. The external name is referred to as the key. I inherit many operations from Set. When I'm looking for something like a TreeMap http://java.sun.com/j2se/1.4.2/docs/api/java/util/TreeMap.html So I would expect the following question answered. In which sense is Dictionary specialising HashedCollection? And a remark that the keys are not sorted by default. --Hannes --Hannes On 5/2/10, Michael Haupt <[hidden email]> wrote: > Hi Hannes, > > On Sun, May 2, 2010 at 9:32 PM, Hannes Hirzel <[hidden email]> > 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 > > |
Re: [Documentation] Classes with class comment with size > 1000 chars
|
|
Hi,
On Sun, May 2, 2010 at 9:50 PM, Hannes Hirzel <[hidden email]> wrote: > But what is then the difference to the superclass #HashedCollection. that one is abstract - see its class comment (which is, I believe, one of the better examples). Sets are also HashedCollections, by the way, and that is why THIS: > The comment of class dictionary: > > I represent a set of elements that can be viewed from one of two > perspectives: a set of associations, or a container of values that are > externally named where the name can be any object that responds to =. > The external name is referred to as the key. I inherit many > operations from Set. ... makes me itch. Dictionary claims to "inherit" operations from Set, when it is a subclass of HashedCollection. OK. We've got a job to do. :-) Best, Michael |
Re: [Documentation] Classes with class comment with size > 1000 chars
|
|
In reply to this post by Michael Haupt-3
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 <[hidden email]> wrote: Hi Hannes, -- Casey Ransberger |
Re: [Documentation] Classes with class comment with size > 1000 chars
|
|
Hi Casey,
On Sun, May 2, 2010 at 10:12 PM, Casey Ransberger <[hidden email]> 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 usually get nervous when people say code is documentation. That may be true for the experienced, for all others, it is not. So that's not a reason to postpone documenting tests in my opinion. > - 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. ... Those two are good reasons. :-) > 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.* True! Agreed! > 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! It does; see above. Best, Michael |
Re: [Documentation] Classes with class comment with size > 1000 chars
|
|
In reply to this post by Casey Ransberger-2
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 <[hidden email]> 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 <[hidden email]> wrote: > >> Hi Hannes, >> >> On Sun, May 2, 2010 at 9:32 PM, Hannes Hirzel <[hidden email]> >> 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 > |
Re: [Documentation] Classes with class comment with size > 1000 chars
|
|
In reply to this post by Michael Haupt-3
Comment inline below.
On Sun, May 2, 2010 at 1:25 PM, Michael Haupt <[hidden email]> wrote: Hi Casey, Hey, me too! But in the case of tests, I actually disagree. I'm not arguing that we shouldn't document our test classes, but I will point out that *a test is an example usage* and *examples are documentation.*
One thing I really enjoy, actually, is when a class comment says something like "Please see the test cases in FooTests for some concrete examples." This is totally off topic, but I think this is kind of cool (and totally pink-plane thinking:)
<big snip> -- Casey Ransberger |
«
Return to Squeak - Dev
|
1 view|%1 views
| Free forum by Nabble | Edit this page |