Comments or no integration: a simple choice for you

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
18 messages Options
Reply | Threaded
Open this post in threaded view
|

Comments or no integration: a simple choice for you

Stéphane Ducasse
Hi guys

I decided that I will not integrate any code that is not documented in Pharo.

I strongly suggest to remove from Pharo-dev packages whose classes are not commented.
I'm not sure that I will look at code or answer question to code that is not commented.
We should change our mindset and it seems that we do not care, so we should take radical decisions:
        less changes, less progress, more comments.

And for once I will not bash the past. Smalltalk was always with methods fully documented.
We are just plain lazy and this is a shame.

Stef
Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice for you

garduino
Yes I agree.

Documentation is a key part of any software, without doc, all is more
hard and painful.

I would add also proper naming of things, and not use criptics things
as "el", "dr", etc that certainly don't help with the code
understanding.

Cheers.


2010/12/5 Stéphane Ducasse <[hidden email]>:

> Hi guys
>
> I decided that I will not integrate any code that is not documented in Pharo.
>
> I strongly suggest to remove from Pharo-dev packages whose classes are not commented.
> I'm not sure that I will look at code or answer question to code that is not commented.
> We should change our mindset and it seems that we do not care, so we should take radical decisions:
>        less changes, less progress, more comments.
>
> And for once I will not bash the past. Smalltalk was always with methods fully documented.
> We are just plain lazy and this is a shame.
>
> Stef
>

Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice for you

Schwab,Wilhelm K
In reply to this post by Stéphane Ducasse
Stef,

IMHO, before we take such a stance, we should have a package comment pane and encourage its use.  A complex package is probably best documented with a good high-level description and some type of example(s), which can take the form of do-its in a package comment.  

A package comment could be expected to provide or point to appropriate examples/tests for the package.  That solves the problem while allowing for contributors' styles and the "shape" of the code.  Something with just a few classes is well-served by class comments; something with many classes presents the would-be reader with a treasure hunt to find the correct class comment.

We might also create a #help mechanism so that something like

   CzAuthor help

gathers class and package comments that might exist.

Bill



________________________________________
From: [hidden email] [[hidden email]] On Behalf Of Stéphane Ducasse [[hidden email]]
Sent: Sunday, December 05, 2010 3:52 PM
To: [hidden email] Development
Subject: [Pharo-project] Comments or no integration: a simple choice for you

Hi guys

I decided that I will not integrate any code that is not documented in Pharo.

I strongly suggest to remove from Pharo-dev packages whose classes are not commented.
I'm not sure that I will look at code or answer question to code that is not commented.
We should change our mindset and it seems that we do not care, so we should take radical decisions:
        less changes, less progress, more comments.

And for once I will not bash the past. Smalltalk was always with methods fully documented.
We are just plain lazy and this is a shame.

Stef

Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice for you

laurent laffont

On Sun, Dec 5, 2010 at 10:10 PM, Schwab,Wilhelm K <[hidden email]> wrote:
Stef,

IMHO, before we take such a stance, we should have a package comment pane and encourage its use.  A complex package is probably best documented with a good high-level description and some type of example(s), which can take the form of do-its in a package comment.

A package comment could be expected to provide or point to appropriate examples/tests for the package.  That solves the problem while allowing for contributors' styles and the "shape" of the code.  Something with just a few classes is well-served by class comments; something with many classes presents the would-be reader with a treasure hunt to find the correct class comment.

We might also create a #help mechanism so that something like

  CzAuthor help

gathers class and package comments that might exist.


HelpSystem does this and is included in PharoCore. See http://www.pharocasts.com/2010/09/document-with-helpsystem.html

Laurent


 

Bill



________________________________________
From: [hidden email] [[hidden email]] On Behalf Of Stéphane Ducasse [[hidden email]]
Sent: Sunday, December 05, 2010 3:52 PM
To: [hidden email] Development
Subject: [Pharo-project] Comments or no integration: a simple choice for you

Hi guys

I decided that I will not integrate any code that is not documented in Pharo.

I strongly suggest to remove from Pharo-dev packages whose classes are not commented.
I'm not sure that I will look at code or answer question to code that is not commented.
We should change our mindset and it seems that we do not care, so we should take radical decisions:
       less changes, less progress, more comments.

And for once I will not bash the past. Smalltalk was always with methods fully documented.
We are just plain lazy and this is a shame.

Stef


Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice for you

Mariano Martinez Peck
In reply to this post by Stéphane Ducasse


On Sun, Dec 5, 2010 at 9:52 PM, Stéphane Ducasse <[hidden email]> wrote:
Hi guys

I decided that I will not integrate any code that is not documented in Pharo.

I strongly suggest to remove from Pharo-dev packages whose classes are not commented.

I think this is not a good idea...look this approx:



    | pharoCorePackages packagesDev nonCommentedClasses totalClasses |
    pharoCorePackages := #('MultilingualTests' 'Morphic' 'ToolBuilder-Kernel' 'PackageInfo' 'Polymorph-ToolBuilder' 'Network-Kernel' 'Network-Protocols' 'Compiler' 'System-Finalization' 'Settings-Graphics' 'Collections' 'Network-RemoteDirectory' 'Traits' 'Network-URI' 'Settings-Display' 'Collections-Abstract' 'Settings-Compiler' 'MonticelloMocks' 'ScriptLoader11' 'System-Digital Signatures' 'System-Localization' 'MenuRegistration' 'Polymorph-TaskbarIcons' 'Monticello' 'ToolBuilder-Morphic' 'MCDirtyPackage' 'Collections-Weak' 'Settings-Polymorph' 'Tests' 'HelpSystem-Core-Utilities' 'SUnit' 'Collections-Text' 'Compression' 'Morphic-MorphTreeWidget' 'HelpSystem-Core' 'ToolsTest' 'Gofer-Core' 'Gofer-Tests' 'Collections-Stack' 'FreeType' 'MonticelloConfigurations' 'Polymorph-Geometry' 'Collections-Support' 'SUnitGUI' 'HelpSystem-Core-Model' 'Tests-VM' 'System-Change Notification' 'System' 'Tests-ObjectsAsMethods' 'HostMenus' 'Network-MIME' 'Network-RFC822' 'VB-Regex' 'TrueType' 'DeprecatedPreferences' 'System-Clipboard' 'System-Settings' 'MorphicTests' 'System-Serial Port' 'NetworkTests' 'Collections-Unordered' 'System-Changes' 'System-Object Storage' 'Collections-Traits' 'System-Platforms' 'Tests-PrimCallController' 'Morphic-TrueType' 'Multilingual' 'Graphics' 'Collections-Strings' 'KernelTests' 'System-FileRegistry' 'Tests-Bugs' 'ToolBuilder-SUnit' 'Tests-Release' 'Morphic-Balloon' 'Settings-Network' 'System-Applications' 'Polymorph-Tools-Diff' 'Settings-Tools' 'ScriptLoader' 'ST80' 'FreeTypeSubPixelAntiAliasing' 'Settings-Kernel' 'Settings-System' 'CompilerTests' 'System-Tools' 'System-Hashing' 'System-Download' 'Collections-Streams' 'Tests-SystemChangeNotification' 'GraphicsTests' 'Polymorph-Widgets' 'Kernel' 'Tools' 'Settings-FreeType' 'FreeTypeTests' 'Settings-Monticello' 'HelpSystem-Tests' 'Polymorph-EventEnhancements' 'System-Support' 'MonticelloGUI' 'System-FilePackage' 'System-Object Events' 'Announcements' 'System-Text' 'Exceptions' 'Network-UUID' 'System-Pools' 'FixUnderscores' 'HelpSystem-Core-UI' 'GraphicsResources' 'Files' 'Gofer' 'Network-MailSending' 'Collections-Arrayed' 'CollectionsTests' 'Balloon' 'Network-Url' 'Collections-Sequenceable' ).
    packagesDev := (PackageInfo allPackages
                collect: [:each | each packageName])
                difference: pharoCorePackages.
    nonCommentedClasses := packagesDev
        inject: 0
        into: [:sum :each | sum + (((PackageInfo named: each) classes
                    select: [:aClass | aClass comment asString includesSubString: 'is xxxxxxxxx.']) size)].
    Transcript show: 'nonCommentedClasses: ', nonCommentedClasses asString.
   
    totalClasses :=  packagesDev inject: 0 into: [:sum :each | sum + (PackageInfo named: each) classes size ].
    Transcript show: 'totalClasses: ', totalClasses asString.



Shows:

nonCommentedClasses: 1116
totalClasses: 1369

 
I'm not sure that I will look at code or answer question to code that is not commented.
We should change our mindset and it seems that we do not care, so we should take radical decisions:
       less changes, less progress, more comments.

And for once I will not bash the past. Smalltalk was always with methods fully documented.
We are just plain lazy and this is a shame.

Stef

Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice for you

tfleig
In reply to this post by Stéphane Ducasse
As a new reader of Pharo code I have frequently been dismayed at the
lack of even the most cursory comments for many of the classes.

Yes, good code (short methods, good names, etc.) doesn't require
commenting, but a brief overview of a class's purpose and essential
processing can help quite a lot. Examples of common usage patterns are
essential if you want people to use the class properly.

Good decision.

TF

On Sun, Dec 5, 2010 at 12:52 PM, Stéphane Ducasse
<[hidden email]> wrote:

> Hi guys
>
> I decided that I will not integrate any code that is not documented in Pharo.
>
> I strongly suggest to remove from Pharo-dev packages whose classes are not commented.
> I'm not sure that I will look at code or answer question to code that is not commented.
> We should change our mindset and it seems that we do not care, so we should take radical decisions:
>        less changes, less progress, more comments.
>
> And for once I will not bash the past. Smalltalk was always with methods fully documented.
> We are just plain lazy and this is a shame.
>
> Stef
>

Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice for you

csrabak
In reply to this post by Mariano Martinez Peck
Mariano,

Precisely due the size of the problem as you estimated that Stef's plan is a Good Idea®.
 
The next step would be a Pareto classification, as it can be accepted (I hope) that SUnit has more history (and it is documented elsewhere, like PBE book) than other classes which even the name of it or its methods may be insufficient to arrive at for what is the class.

We should create IRC meetings, sprints, etc. specially targeted to document these classes.

my .019999...

--
Cesar Rabak


Em 05/12/2010 20:07, Mariano Martinez Peck < [hidden email] > escreveu:

On Sun, Dec 5, 2010 at 9:52 PM, Stéphane Ducasse <[hidden email]> wrote:

Hi guys
 
 I decided that I will not integrate any code that is not documented in Pharo.
 
 I strongly suggest to remove from Pharo-dev packages whose classes are not commented.


I think this is not a good idea...look this approx:



 | pharoCorePackages packagesDev nonCommentedClasses totalClasses |
 pharoCorePackages := #('MultilingualTests' 'Morphic' 'ToolBuilder-Kernel' 'PackageInfo' 'Polymorph-ToolBuilder' 'Network-Kernel' 'Network-Protocols' 'Compiler' 'System-Finalization' 'Settings-Graphics' 'Collections' 'Network-RemoteDirectory' 'Traits' 'Network-URI' 'Settings-Display' 'Collections-Abstract' 'Settings-Compiler' 'MonticelloMocks' 'ScriptLoader11' 'System-Digital Signatures' 'System-Localization' 'MenuRegistration' 'Polymorph-TaskbarIcons' 'Monticello' 'ToolBuilder-Morphic' 'MCDirtyPackage' 'Collections-Weak' 'Settings-Polymorph' 'Tests' 'HelpSystem-Core-Utilities' 'SUnit' 'Collections-Text' 'Compression' 'Morphic-MorphTreeWidget' 'HelpSystem-Core' 'ToolsTest' 'Gofer-Core' 'Gofer-Tests' 'Collections-Stack' 'FreeType' 'MonticelloConfigurations' 'Polymorph-Geometry' 'Collections-Support' 'SUnitGUI' 'HelpSystem-Core-Model' 'Tests-VM' 'System-Change Notification' 'System' 'Tests-ObjectsAsMethods' 'HostMenus' 'Network-MIME' 'Network-RFC822' 'VB-Regex' 'TrueType' 'Depr
 ecatedPreferences' 'System-Clipboard' 'System-Settings' 'MorphicTests' 'System-Serial Port' 'NetworkTests' 'Collections-Unordered' 'System-Changes' 'System-Object Storage' 'Collections-Traits' 'System-Platforms' 'Tests-PrimCallController' 'Morphic-TrueType' 'Multilingual' 'Graphics' 'Collections-Strings' 'KernelTests' 'System-FileRegistry' 'Tests-Bugs' 'ToolBuilder-SUnit' 'Tests-Release' 'Morphic-Balloon' 'Settings-Network' 'System-Applications' 'Polymorph-Tools-Diff' 'Settings-Tools' 'ScriptLoader' 'ST80' 'FreeTypeSubPixelAntiAliasing' 'Settings-Kernel' 'Settings-System' 'CompilerTests' 'System-Tools' 'System-Hashing' 'System-Download' 'Collections-Streams' 'Tests-SystemChangeNotification' 'GraphicsTests' 'Polymorph-Widgets' 'Kernel' 'Tools' 'Settings-FreeType' 'FreeTypeTests' 'Settings-Monticello' 'HelpSystem-Tests' 'Polymorph-EventEnhancements' 'System-Support' 'MonticelloGUI' 'System-FilePackage' 'System-Object Events' 'Announcements' 'System-Text' 'Exceptions' 'Network-
 UUID' 'System-Pools' 'FixUnderscores' 'HelpSystem-Core-UI' 'GraphicsResources' 'Files' 'Gofer' 'Network-MailSending' 'Collections-Arrayed' 'CollectionsTests' 'Balloon' 'Network-Url' 'Collections-Sequenceable' ).
 packagesDev := (PackageInfo allPackages
 collect: [:each | each packageName])
 difference: pharoCorePackages.
 nonCommentedClasses := packagesDev
 inject: 0
 into: [:sum :each | sum + (((PackageInfo named: each) classes
 select: [:aClass | aClass comment asString includesSubString: 'is xxxxxxxxx.']) size)].
 Transcript show: 'nonCommentedClasses: ', nonCommentedClasses asString.
 
 totalClasses :=  packagesDev inject: 0 into: [:sum :each | sum + (PackageInfo named: each) classes size ].
 Transcript show: 'totalClasses: ', totalClasses asString.



Shows:

nonCommentedClasses: 1116
totalClasses: 1369


I'm not sure that I will look at code or answer question to code that is not commented.
 We should change our mindset and it seems that we do not care, so we should take radical decisions:
 less changes, less progress, more comments.
 
 And for once I will not bash the past. Smalltalk was always with methods fully documented.
 We are just plain lazy and this is a shame.
 
 Stef



 

Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice for you

Mariano Martinez Peck


On Mon, Dec 6, 2010 at 4:32 PM, <[hidden email]> wrote:
Mariano,

Precisely due the size of the problem as you estimated that Stef's plan is a Good Idea®.

The good idae is to push and promote people to put class comments, but not to remove not commented classes from Dev, bacause otherise, you will need to remove 80% of the classes.
 

The next step would be a Pareto classification, as it can be accepted (I hope) that SUnit has more history (and it is documented elsewhere, like PBE book) than other classes which even the name of it or its methods may be insufficient to arrive at for what is the class.

We should create IRC meetings, sprints, etc. specially targeted to document these classes.

my .019999...

--
Cesar Rabak


Em 05/12/2010 20:07, Mariano Martinez Peck < [hidden email] > escreveu:

On Sun, Dec 5, 2010 at 9:52 PM, Stéphane Ducasse <[hidden email]> wrote:

Hi guys

 I decided that I will not integrate any code that is not documented in Pharo.

 I strongly suggest to remove from Pharo-dev packages whose classes are not commented.


I think this is not a good idea...look this approx:



 | pharoCorePackages packagesDev nonCommentedClasses totalClasses |
 pharoCorePackages := #('MultilingualTests' 'Morphic' 'ToolBuilder-Kernel' 'PackageInfo' 'Polymorph-ToolBuilder' 'Network-Kernel' 'Network-Protocols' 'Compiler' 'System-Finalization' 'Settings-Graphics' 'Collections' 'Network-RemoteDirectory' 'Traits' 'Network-URI' 'Settings-Display' 'Collections-Abstract' 'Settings-Compiler' 'MonticelloMocks' 'ScriptLoader11' 'System-Digital Signatures' 'System-Localization' 'MenuRegistration' 'Polymorph-TaskbarIcons' 'Monticello' 'ToolBuilder-Morphic' 'MCDirtyPackage' 'Collections-Weak' 'Settings-Polymorph' 'Tests' 'HelpSystem-Core-Utilities' 'SUnit' 'Collections-Text' 'Compression' 'Morphic-MorphTreeWidget' 'HelpSystem-Core' 'ToolsTest' 'Gofer-Core' 'Gofer-Tests' 'Collections-Stack' 'FreeType' 'MonticelloConfigurations' 'Polymorph-Geometry' 'Collections-Support' 'SUnitGUI' 'HelpSystem-Core-Model' 'Tests-VM' 'System-Change Notification' 'System' 'Tests-ObjectsAsMethods' 'HostMenus' 'Network-MIME' 'Network-RFC822' 'VB-Regex' 'TrueType' 'Depr
 ecatedPreferences' 'System-Clipboard' 'System-Settings' 'MorphicTests' 'System-Serial Port' 'NetworkTests' 'Collections-Unordered' 'System-Changes' 'System-Object Storage' 'Collections-Traits' 'System-Platforms' 'Tests-PrimCallController' 'Morphic-TrueType' 'Multilingual' 'Graphics' 'Collections-Strings' 'KernelTests' 'System-FileRegistry' 'Tests-Bugs' 'ToolBuilder-SUnit' 'Tests-Release' 'Morphic-Balloon' 'Settings-Network' 'System-Applications' 'Polymorph-Tools-Diff' 'Settings-Tools' 'ScriptLoader' 'ST80' 'FreeTypeSubPixelAntiAliasing' 'Settings-Kernel' 'Settings-System' 'CompilerTests' 'System-Tools' 'System-Hashing' 'System-Download' 'Collections-Streams' 'Tests-SystemChangeNotification' 'GraphicsTests' 'Polymorph-Widgets' 'Kernel' 'Tools' 'Settings-FreeType' 'FreeTypeTests' 'Settings-Monticello' 'HelpSystem-Tests' 'Polymorph-EventEnhancements' 'System-Support' 'MonticelloGUI' 'System-FilePackage' 'System-Object Events' 'Announcements' 'System-Text' 'Exceptions' 'Network-
 UUID' 'System-Pools' 'FixUnderscores' 'HelpSystem-Core-UI' 'GraphicsResources' 'Files' 'Gofer' 'Network-MailSending' 'Collections-Arrayed' 'CollectionsTests' 'Balloon' 'Network-Url' 'Collections-Sequenceable' ).
 packagesDev := (PackageInfo allPackages
 collect: [:each | each packageName])
 difference: pharoCorePackages.
 nonCommentedClasses := packagesDev
 inject: 0
 into: [:sum :each | sum + (((PackageInfo named: each) classes
 select: [:aClass | aClass comment asString includesSubString: 'is xxxxxxxxx.']) size)].
 Transcript show: 'nonCommentedClasses: ', nonCommentedClasses asString.

 totalClasses :=  packagesDev inject: 0 into: [:sum :each | sum + (PackageInfo named: each) classes size ].
 Transcript show: 'totalClasses: ', totalClasses asString.



Shows:

nonCommentedClasses: 1116
totalClasses: 1369


I'm not sure that I will look at code or answer question to code that is not commented.
 We should change our mindset and it seems that we do not care, so we should take radical decisions:
 less changes, less progress, more comments.

 And for once I will not bash the past. Smalltalk was always with methods fully documented.
 We are just plain lazy and this is a shame.

 Stef






Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice for you

Sean P. DeNigris
Administrator
In reply to this post by laurent laffont
laurent laffont wrote
> IMHO, before we take such a stance, we should have a package comment pane
> and encourage its use.  A complex package is probably best documented with a
> good high-level description and some type of example(s), which can take the
> form of do-its in a package comment.

HelpSystem does this and is included in PharoCore. See
http://www.pharocasts.com/2010/09/document-with-helpsystem.html
What if the source pane in the browser showed the first page of the package's help when only a package name was selected?  And there could be a shortcut/cataegory-list-menu-option to open the help browser on the package's help from the browser!

Sean
Cheers,
Sean
Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice for you

Sean P. DeNigris
Administrator
In reply to this post by Mariano Martinez Peck
I love this idea!

Mariano Martinez Peck wrote
The good idae is to push and promote people to put class comments, but not
to remove not commented classes from Dev, bacause otherise, you will need to
remove 80% of the classes.
It seemed to me this plan is being suggested precisely because "push and promote" has not produced results.  In face, I would say this grand challenge is a pretty good "push" ;-)  Plus, it's more fun than "trying to put more comments before the next release".

Fortune favors the bold!

Sean
Cheers,
Sean
Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice for you

csrabak
Otherwise we can find out how small the dev image can really be. . . ;-)
 



Em 06/12/2010 16:46, Sean P. DeNigris < [hidden email] > escreveu:

I love this idea!


Mariano Martinez Peck wrote:
>
> The good idae is to push and promote people to put class comments, but not
> to remove not commented classes from Dev, bacause otherise, you will need
> to
> remove 80% of the classes.
>

It seemed to me this plan is being suggested precisely because "push and
promote" has not produced results.  In face, I would say this grand
challenge is a pretty good "push" ;-)  Plus, it's more fun than "trying to
put more comments before the next release".

Fortune favors the bold!

Sean
--
View this message in context: http://forum.world.st/Comments-or-no-integration-a-simple-choice-for-you-tp3073643p3075065.html
Sent from the Pharo Smalltalk mailing list archive at Nabble.com.



Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice for you

hernanmd
In reply to this post by Stéphane Ducasse
Hi Stef,

To me class comments are not *that* useful. Most of the time I search
explanations for contexts of use, which usually involves many classes
and methods everywhere. I would remove packages which doesn't include
at least some brief or general comments of the main classes or
methods, this is less effort for a developer to remember and to
document. Or it could be a start.
Hernán

2010/12/5 Stéphane Ducasse <[hidden email]>:

> Hi guys
>
> I decided that I will not integrate any code that is not documented in Pharo.
>
> I strongly suggest to remove from Pharo-dev packages whose classes are not commented.
> I'm not sure that I will look at code or answer question to code that is not commented.
> We should change our mindset and it seems that we do not care, so we should take radical decisions:
>        less changes, less progress, more comments.
>
> And for once I will not bash the past. Smalltalk was always with methods fully documented.
> We are just plain lazy and this is a shame.
>
> Stef
>



--
Hernán Morales
Information Technology Manager,
Institute of Veterinary Genetics.
National Scientific and Technical Research Council (CONICET).
La Plata (1900), Buenos Aires, Argentina.
Telephone: +54 (0221) 421-1799.
Internal: 422
Fax: 425-7980 or 421-1799.

Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice for you

Stéphane Ducasse
In reply to this post by Mariano Martinez Peck
> The good idae is to push and promote people to put class comments, but not to remove not commented classes from Dev, bacause otherise, you will need to remove 80% of the classes.


So this is simple to start fixing some of them.
I think that without such objectives we will never make any progress and we should.

so what are the first 5% of packages that are not documented.

Stef

> The next step would be a Pareto classification, as it can be accepted (I hope) that SUnit has more history (and it is documented elsewhere, like PBE book) than other classes which even the name of it or its methods may be insufficient to arrive at for what is the class.
>
> We should create IRC meetings, sprints, etc. specially targeted to document these classes.
>
> my .019999...
>
> --
> Cesar Rabak
>
>
> Em 05/12/2010 20:07, Mariano Martinez Peck < [hidden email] > escreveu:
>
> On Sun, Dec 5, 2010 at 9:52 PM, Stéphane Ducasse <[hidden email]> wrote:
>
> Hi guys
>
>  I decided that I will not integrate any code that is not documented in Pharo.
>
>  I strongly suggest to remove from Pharo-dev packages whose classes are not commented.
>
>
> I think this is not a good idea...look this approx:
>
>
>
>  | pharoCorePackages packagesDev nonCommentedClasses totalClasses |
>  pharoCorePackages := #('MultilingualTests' 'Morphic' 'ToolBuilder-Kernel' 'PackageInfo' 'Polymorph-ToolBuilder' 'Network-Kernel' 'Network-Protocols' 'Compiler' 'System-Finalization' 'Settings-Graphics' 'Collections' 'Network-RemoteDirectory' 'Traits' 'Network-URI' 'Settings-Display' 'Collections-Abstract' 'Settings-Compiler' 'MonticelloMocks' 'ScriptLoader11' 'System-Digital Signatures' 'System-Localization' 'MenuRegistration' 'Polymorph-TaskbarIcons' 'Monticello' 'ToolBuilder-Morphic' 'MCDirtyPackage' 'Collections-Weak' 'Settings-Polymorph' 'Tests' 'HelpSystem-Core-Utilities' 'SUnit' 'Collections-Text' 'Compression' 'Morphic-MorphTreeWidget' 'HelpSystem-Core' 'ToolsTest' 'Gofer-Core' 'Gofer-Tests' 'Collections-Stack' 'FreeType' 'MonticelloConfigurations' 'Polymorph-Geometry' 'Collections-Support' 'SUnitGUI' 'HelpSystem-Core-Model' 'Tests-VM' 'System-Change Notification' 'System' 'Tests-ObjectsAsMethods' 'HostMenus' 'Network-MIME' 'Network-RFC822' 'VB-Regex' 'TrueType' 'Depr
>  ecatedPreferences' 'System-Clipboard' 'System-Settings' 'MorphicTests' 'System-Serial Port' 'NetworkTests' 'Collections-Unordered' 'System-Changes' 'System-Object Storage' 'Collections-Traits' 'System-Platforms' 'Tests-PrimCallController' 'Morphic-TrueType' 'Multilingual' 'Graphics' 'Collections-Strings' 'KernelTests' 'System-FileRegistry' 'Tests-Bugs' 'ToolBuilder-SUnit' 'Tests-Release' 'Morphic-Balloon' 'Settings-Network' 'System-Applications' 'Polymorph-Tools-Diff' 'Settings-Tools' 'ScriptLoader' 'ST80' 'FreeTypeSubPixelAntiAliasing' 'Settings-Kernel' 'Settings-System' 'CompilerTests' 'System-Tools' 'System-Hashing' 'System-Download' 'Collections-Streams' 'Tests-SystemChangeNotification' 'GraphicsTests' 'Polymorph-Widgets' 'Kernel' 'Tools' 'Settings-FreeType' 'FreeTypeTests' 'Settings-Monticello' 'HelpSystem-Tests' 'Polymorph-EventEnhancements' 'System-Support' 'MonticelloGUI' 'System-FilePackage' 'System-Object Events' 'Announcements' 'System-Text' 'Exceptions' 'Network-
>  UUID' 'System-Pools' 'FixUnderscores' 'HelpSystem-Core-UI' 'GraphicsResources' 'Files' 'Gofer' 'Network-MailSending' 'Collections-Arrayed' 'CollectionsTests' 'Balloon' 'Network-Url' 'Collections-Sequenceable' ).
>  packagesDev := (PackageInfo allPackages
>  collect: [:each | each packageName])
>  difference: pharoCorePackages.
>  nonCommentedClasses := packagesDev
>  inject: 0
>  into: [:sum :each | sum + (((PackageInfo named: each) classes
>  select: [:aClass | aClass comment asString includesSubString: 'is xxxxxxxxx.']) size)].
>  Transcript show: 'nonCommentedClasses: ', nonCommentedClasses asString.
>
>  totalClasses :=  packagesDev inject: 0 into: [:sum :each | sum + (PackageInfo named: each) classes size ].
>  Transcript show: 'totalClasses: ', totalClasses asString.
>
>
>
> Shows:
>
> nonCommentedClasses: 1116
> totalClasses: 1369
>
>
> I'm not sure that I will look at code or answer question to code that is not commented.
>  We should change our mindset and it seems that we do not care, so we should take radical decisions:
>  less changes, less progress, more comments.
>
>  And for once I will not bash the past. Smalltalk was always with methods fully documented.
>  We are just plain lazy and this is a shame.
>
>  Stef
>
>
>
>
>
>


Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice for you

Alexandre Bergel
A small script that gives the most referenced classes that are not commented:
I run the test in an image with Moose and Spy.
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
"Get the number of references per class"
d := Dictionary new.
Smalltalk allClasses do: [ :cls | cls methods do: [:cm | (cm literals select: [:l | l isKindOf: Association ])
                do: [:assoc |
                        (assoc value isBehavior)
                                ifTrue: [d at: assoc value put: (d at: assoc value ifAbsentPut: [0] ) + 1]]]].
associations := d associations asSortedCollection: [:a1 :a2 | a2 value < a1 value].

"Get the classes that are not commented"
associations select: [:ass | ass key comment isNil or: [ass key comment isEmpty or: [ass key comment asString includesSubString: 'xxxxxx']]]
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

The first 30 entries:
SortedCollectionTest->307
HeapTest->304
IntervalTest->250
DictionaryTest->192
BagTest->167
RxMatcherTest->166
PluggableTextMorph->149
MooseModel->144
UIThemeWatery2->132
SystemChangeNotifier->132
PPSmalltalkParserTests->129
FAMIXClassNavigationTest->128
PPJavaSyntax->128
PPSmalltalkGrammarTests->128
RBRefactoryTestDataApp->123
NSFileStream->118
NSRWBinaryOrTextStream->109
LogicalFont->109
NSMultiByteBinaryOrTextStream->108
UIThemeW2K->103
MCWorkingCopy->101
BrowserEnvironment->97
DemoSettingStyle->94
PPJavaLexiconTests->94
MCClassDefinition->93
NSAbstractInflateStream->92
MCWorkingCopyBrowser->91
NSCollectionStreamTest->91
GMMetaObject->91
ExceptionTester->90


Cheers,
Alexandre


On 7 Dec 2010, at 10:48, Stéphane Ducasse wrote:

>> The good idae is to push and promote people to put class comments, but not to remove not commented classes from Dev, bacause otherise, you will need to remove 80% of the classes.
>
>
> So this is simple to start fixing some of them.
> I think that without such objectives we will never make any progress and we should.
>
> so what are the first 5% of packages that are not documented.
>
> Stef
>
>> The next step would be a Pareto classification, as it can be accepted (I hope) that SUnit has more history (and it is documented elsewhere, like PBE book) than other classes which even the name of it or its methods may be insufficient to arrive at for what is the class.
>>
>> We should create IRC meetings, sprints, etc. specially targeted to document these classes.
>>
>> my .019999...
>>
>> --
>> Cesar Rabak
>>
>>
>> Em 05/12/2010 20:07, Mariano Martinez Peck < [hidden email] > escreveu:
>>
>> On Sun, Dec 5, 2010 at 9:52 PM, Stéphane Ducasse <[hidden email]> wrote:
>>
>> Hi guys
>>
>> I decided that I will not integrate any code that is not documented in Pharo.
>>
>> I strongly suggest to remove from Pharo-dev packages whose classes are not commented.
>>
>>
>> I think this is not a good idea...look this approx:
>>
>>
>>
>> | pharoCorePackages packagesDev nonCommentedClasses totalClasses |
>> pharoCorePackages := #('MultilingualTests' 'Morphic' 'ToolBuilder-Kernel' 'PackageInfo' 'Polymorph-ToolBuilder' 'Network-Kernel' 'Network-Protocols' 'Compiler' 'System-Finalization' 'Settings-Graphics' 'Collections' 'Network-RemoteDirectory' 'Traits' 'Network-URI' 'Settings-Display' 'Collections-Abstract' 'Settings-Compiler' 'MonticelloMocks' 'ScriptLoader11' 'System-Digital Signatures' 'System-Localization' 'MenuRegistration' 'Polymorph-TaskbarIcons' 'Monticello' 'ToolBuilder-Morphic' 'MCDirtyPackage' 'Collections-Weak' 'Settings-Polymorph' 'Tests' 'HelpSystem-Core-Utilities' 'SUnit' 'Collections-Text' 'Compression' 'Morphic-MorphTreeWidget' 'HelpSystem-Core' 'ToolsTest' 'Gofer-Core' 'Gofer-Tests' 'Collections-Stack' 'FreeType' 'MonticelloConfigurations' 'Polymorph-Geometry' 'Collections-Support' 'SUnitGUI' 'HelpSystem-Core-Model' 'Tests-VM' 'System-Change Notification' 'System' 'Tests-ObjectsAsMethods' 'HostMenus' 'Network-MIME' 'Network-RFC822' 'VB-Regex' 'TrueType' 'Depr
>> ecatedPreferences' 'System-Clipboard' 'System-Settings' 'MorphicTests' 'System-Serial Port' 'NetworkTests' 'Collections-Unordered' 'System-Changes' 'System-Object Storage' 'Collections-Traits' 'System-Platforms' 'Tests-PrimCallController' 'Morphic-TrueType' 'Multilingual' 'Graphics' 'Collections-Strings' 'KernelTests' 'System-FileRegistry' 'Tests-Bugs' 'ToolBuilder-SUnit' 'Tests-Release' 'Morphic-Balloon' 'Settings-Network' 'System-Applications' 'Polymorph-Tools-Diff' 'Settings-Tools' 'ScriptLoader' 'ST80' 'FreeTypeSubPixelAntiAliasing' 'Settings-Kernel' 'Settings-System' 'CompilerTests' 'System-Tools' 'System-Hashing' 'System-Download' 'Collections-Streams' 'Tests-SystemChangeNotification' 'GraphicsTests' 'Polymorph-Widgets' 'Kernel' 'Tools' 'Settings-FreeType' 'FreeTypeTests' 'Settings-Monticello' 'HelpSystem-Tests' 'Polymorph-EventEnhancements' 'System-Support' 'MonticelloGUI' 'System-FilePackage' 'System-Object Events' 'Announcements' 'System-Text' 'Exceptions' 'Network-
>> UUID' 'System-Pools' 'FixUnderscores' 'HelpSystem-Core-UI' 'GraphicsResources' 'Files' 'Gofer' 'Network-MailSending' 'Collections-Arrayed' 'CollectionsTests' 'Balloon' 'Network-Url' 'Collections-Sequenceable' ).
>> packagesDev := (PackageInfo allPackages
>> collect: [:each | each packageName])
>> difference: pharoCorePackages.
>> nonCommentedClasses := packagesDev
>> inject: 0
>> into: [:sum :each | sum + (((PackageInfo named: each) classes
>> select: [:aClass | aClass comment asString includesSubString: 'is xxxxxxxxx.']) size)].
>> Transcript show: 'nonCommentedClasses: ', nonCommentedClasses asString.
>>
>> totalClasses :=  packagesDev inject: 0 into: [:sum :each | sum + (PackageInfo named: each) classes size ].
>> Transcript show: 'totalClasses: ', totalClasses asString.
>>
>>
>>
>> Shows:
>>
>> nonCommentedClasses: 1116
>> totalClasses: 1369
>>
>>
>> I'm not sure that I will look at code or answer question to code that is not commented.
>> We should change our mindset and it seems that we do not care, so we should take radical decisions:
>> less changes, less progress, more comments.
>>
>> And for once I will not bash the past. Smalltalk was always with methods fully documented.
>> We are just plain lazy and this is a shame.
>>
>> Stef
>>
>>
>>
>>
>>
>>
>
>

--
_,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:
Alexandre Bergel  http://www.bergel.eu
^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.






Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice foryou

Gary Chambers-4
Naturally, every method of a class references its own class as a literal...
Also, class-side methods not accounted for.

Easy enough to change the script to higlight only external references:

d := Dictionary new.
Smalltalk allClasses, (Smalltalk allClasses collect: [:cls | cls class]) do:
[ :cls |
 cls methods do: [:cm | (cm literals select: [:l | l isKindOf:
Association ])
  do: [:assoc |
   (assoc value isBehavior and: [assoc value ~~ cls])
    ifTrue: [d at: assoc value put: (d at: assoc value ifAbsentPut: [0] ) +
1]]]].
associations := d associations asSortedCollection: [:a1 :a2 | a2 value < a1
value].
associations select: [:ass | ass key comment isNil or: [ass key comment
isEmpty or: [ass key comment asString includesSubString: 'xxxxxx']]]

Regards, Gary

----- Original Message -----
From: "Alexandre Bergel" <[hidden email]>
To: <[hidden email]>
Sent: Tuesday, December 07, 2010 2:53 PM
Subject: Re: [Pharo-project] Comments or no integration: a simple choice
foryou


A small script that gives the most referenced classes that are not
commented:
I run the test in an image with Moose and Spy.
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
"Get the number of references per class"
d := Dictionary new.
Smalltalk allClasses do: [ :cls | cls methods do: [:cm | (cm literals
select: [:l | l isKindOf: Association ])
do: [:assoc |
(assoc value isBehavior)
ifTrue: [d at: assoc value put: (d at: assoc value ifAbsentPut: [0] ) +
1]]]].
associations := d associations asSortedCollection: [:a1 :a2 | a2 value < a1
value].

"Get the classes that are not commented"
associations select: [:ass | ass key comment isNil or: [ass key comment
isEmpty or: [ass key comment asString includesSubString: 'xxxxxx']]]
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

The first 30 entries:
SortedCollectionTest->307
HeapTest->304
IntervalTest->250
DictionaryTest->192
BagTest->167
RxMatcherTest->166
PluggableTextMorph->149
MooseModel->144
UIThemeWatery2->132
SystemChangeNotifier->132
PPSmalltalkParserTests->129
FAMIXClassNavigationTest->128
PPJavaSyntax->128
PPSmalltalkGrammarTests->128
RBRefactoryTestDataApp->123
NSFileStream->118
NSRWBinaryOrTextStream->109
LogicalFont->109
NSMultiByteBinaryOrTextStream->108
UIThemeW2K->103
MCWorkingCopy->101
BrowserEnvironment->97
DemoSettingStyle->94
PPJavaLexiconTests->94
MCClassDefinition->93
NSAbstractInflateStream->92
MCWorkingCopyBrowser->91
NSCollectionStreamTest->91
GMMetaObject->91
ExceptionTester->90


Cheers,
Alexandre


On 7 Dec 2010, at 10:48, Stéphane Ducasse wrote:

>> The good idae is to push and promote people to put class comments, but
>> not to remove not commented classes from Dev, bacause otherise, you will
>> need to remove 80% of the classes.
>
>
> So this is simple to start fixing some of them.
> I think that without such objectives we will never make any progress and
> we should.
>
> so what are the first 5% of packages that are not documented.
>
> Stef
>
>> The next step would be a Pareto classification, as it can be accepted (I
>> hope) that SUnit has more history (and it is documented elsewhere, like
>> PBE book) than other classes which even the name of it or its methods may
>> be insufficient to arrive at for what is the class.
>>
>> We should create IRC meetings, sprints, etc. specially targeted to
>> document these classes.
>>
>> my .019999...
>>
>> --
>> Cesar Rabak
>>
>>
>> Em 05/12/2010 20:07, Mariano Martinez Peck < [hidden email] >
>> escreveu:
>>
>> On Sun, Dec 5, 2010 at 9:52 PM, Stéphane Ducasse
>> <[hidden email]> wrote:
>>
>> Hi guys
>>
>> I decided that I will not integrate any code that is not documented in
>> Pharo.
>>
>> I strongly suggest to remove from Pharo-dev packages whose classes are
>> not commented.
>>
>>
>> I think this is not a good idea...look this approx:
>>
>>
>>
>> | pharoCorePackages packagesDev nonCommentedClasses totalClasses |
>> pharoCorePackages := #('MultilingualTests' 'Morphic' 'ToolBuilder-Kernel'
>> 'PackageInfo' 'Polymorph-ToolBuilder' 'Network-Kernel'
>> 'Network-Protocols' 'Compiler' 'System-Finalization' 'Settings-Graphics'
>> 'Collections' 'Network-RemoteDirectory' 'Traits' 'Network-URI'
>> 'Settings-Display' 'Collections-Abstract' 'Settings-Compiler'
>> 'MonticelloMocks' 'ScriptLoader11' 'System-Digital Signatures'
>> 'System-Localization' 'MenuRegistration' 'Polymorph-TaskbarIcons'
>> 'Monticello' 'ToolBuilder-Morphic' 'MCDirtyPackage' 'Collections-Weak'
>> 'Settings-Polymorph' 'Tests' 'HelpSystem-Core-Utilities' 'SUnit'
>> 'Collections-Text' 'Compression' 'Morphic-MorphTreeWidget'
>> 'HelpSystem-Core' 'ToolsTest' 'Gofer-Core' 'Gofer-Tests'
>> 'Collections-Stack' 'FreeType' 'MonticelloConfigurations'
>> 'Polymorph-Geometry' 'Collections-Support' 'SUnitGUI'
>> 'HelpSystem-Core-Model' 'Tests-VM' 'System-Change Notification' 'System'
>> 'Tests-ObjectsAsMethods' 'HostMenus' 'Network-MIME' 'Network-RFC822'
>> 'VB-Regex' 'TrueType' 'Depr
>> ecatedPreferences' 'System-Clipboard' 'System-Settings' 'MorphicTests'
>> 'System-Serial Port' 'NetworkTests' 'Collections-Unordered'
>> 'System-Changes' 'System-Object Storage' 'Collections-Traits'
>> 'System-Platforms' 'Tests-PrimCallController' 'Morphic-TrueType'
>> 'Multilingual' 'Graphics' 'Collections-Strings' 'KernelTests'
>> 'System-FileRegistry' 'Tests-Bugs' 'ToolBuilder-SUnit' 'Tests-Release'
>> 'Morphic-Balloon' 'Settings-Network' 'System-Applications'
>> 'Polymorph-Tools-Diff' 'Settings-Tools' 'ScriptLoader' 'ST80'
>> 'FreeTypeSubPixelAntiAliasing' 'Settings-Kernel' 'Settings-System'
>> 'CompilerTests' 'System-Tools' 'System-Hashing' 'System-Download'
>> 'Collections-Streams' 'Tests-SystemChangeNotification' 'GraphicsTests'
>> 'Polymorph-Widgets' 'Kernel' 'Tools' 'Settings-FreeType' 'FreeTypeTests'
>> 'Settings-Monticello' 'HelpSystem-Tests' 'Polymorph-EventEnhancements'
>> 'System-Support' 'MonticelloGUI' 'System-FilePackage' 'System-Object
>> Events' 'Announcements' 'System-Text' 'Exceptions' 'Network-
>> UUID' 'System-Pools' 'FixUnderscores' 'HelpSystem-Core-UI'
>> 'GraphicsResources' 'Files' 'Gofer' 'Network-MailSending'
>> 'Collections-Arrayed' 'CollectionsTests' 'Balloon' 'Network-Url'
>> 'Collections-Sequenceable' ).
>> packagesDev := (PackageInfo allPackages
>> collect: [:each | each packageName])
>> difference: pharoCorePackages.
>> nonCommentedClasses := packagesDev
>> inject: 0
>> into: [:sum :each | sum + (((PackageInfo named: each) classes
>> select: [:aClass | aClass comment asString includesSubString: 'is
>> xxxxxxxxx.']) size)].
>> Transcript show: 'nonCommentedClasses: ', nonCommentedClasses asString.
>>
>> totalClasses :=  packagesDev inject: 0 into: [:sum :each | sum +
>> (PackageInfo named: each) classes size ].
>> Transcript show: 'totalClasses: ', totalClasses asString.
>>
>>
>>
>> Shows:
>>
>> nonCommentedClasses: 1116
>> totalClasses: 1369
>>
>>
>> I'm not sure that I will look at code or answer question to code that is
>> not commented.
>> We should change our mindset and it seems that we do not care, so we
>> should take radical decisions:
>> less changes, less progress, more comments.
>>
>> And for once I will not bash the past. Smalltalk was always with methods
>> fully documented.
>> We are just plain lazy and this is a shame.
>>
>> Stef
>>
>>
>>
>>
>>
>>
>
>

--
_,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:
Alexandre Bergel  http://www.bergel.eu
^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.







Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice foryou

Alexandre Bergel
Indeed. We could also refine it further by identifying the most used classes for a representative sample of the Pharo ecosystem.
It still says StandardFonts, SystemChangeNotifier, FreeTypeSettings, MCPackage, ... have to be commented

Alexandre


On 7 Dec 2010, at 12:29, Gary Chambers wrote:

> Naturally, every method of a class references its own class as a literal...
> Also, class-side methods not accounted for.
>
> Easy enough to change the script to higlight only external references:
>
> d := Dictionary new.
> Smalltalk allClasses, (Smalltalk allClasses collect: [:cls | cls class]) do: [ :cls |
> cls methods do: [:cm | (cm literals select: [:l | l isKindOf: Association ])
> do: [:assoc |
>  (assoc value isBehavior and: [assoc value ~~ cls])
>   ifTrue: [d at: assoc value put: (d at: assoc value ifAbsentPut: [0] ) + 1]]]].
> associations := d associations asSortedCollection: [:a1 :a2 | a2 value < a1 value].
> associations select: [:ass | ass key comment isNil or: [ass key comment isEmpty or: [ass key comment asString includesSubString: 'xxxxxx']]]
>
> Regards, Gary
>
> ----- Original Message ----- From: "Alexandre Bergel" <[hidden email]>
> To: <[hidden email]>
> Sent: Tuesday, December 07, 2010 2:53 PM
> Subject: Re: [Pharo-project] Comments or no integration: a simple choice foryou
>
>
> A small script that gives the most referenced classes that are not commented:
> I run the test in an image with Moose and Spy.
> -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
> "Get the number of references per class"
> d := Dictionary new.
> Smalltalk allClasses do: [ :cls | cls methods do: [:cm | (cm literals select: [:l | l isKindOf: Association ])
> do: [:assoc |
> (assoc value isBehavior)
> ifTrue: [d at: assoc value put: (d at: assoc value ifAbsentPut: [0] ) + 1]]]].
> associations := d associations asSortedCollection: [:a1 :a2 | a2 value < a1 value].
>
> "Get the classes that are not commented"
> associations select: [:ass | ass key comment isNil or: [ass key comment isEmpty or: [ass key comment asString includesSubString: 'xxxxxx']]]
> -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
>
> The first 30 entries:
> SortedCollectionTest->307
> HeapTest->304
> IntervalTest->250
> DictionaryTest->192
> BagTest->167
> RxMatcherTest->166
> PluggableTextMorph->149
> MooseModel->144
> UIThemeWatery2->132
> SystemChangeNotifier->132
> PPSmalltalkParserTests->129
> FAMIXClassNavigationTest->128
> PPJavaSyntax->128
> PPSmalltalkGrammarTests->128
> RBRefactoryTestDataApp->123
> NSFileStream->118
> NSRWBinaryOrTextStream->109
> LogicalFont->109
> NSMultiByteBinaryOrTextStream->108
> UIThemeW2K->103
> MCWorkingCopy->101
> BrowserEnvironment->97
> DemoSettingStyle->94
> PPJavaLexiconTests->94
> MCClassDefinition->93
> NSAbstractInflateStream->92
> MCWorkingCopyBrowser->91
> NSCollectionStreamTest->91
> GMMetaObject->91
> ExceptionTester->90
>
>
> Cheers,
> Alexandre
>
>
> On 7 Dec 2010, at 10:48, Stéphane Ducasse wrote:
>
>>> The good idae is to push and promote people to put class comments, but not to remove not commented classes from Dev, bacause otherise, you will need to remove 80% of the classes.
>>
>>
>> So this is simple to start fixing some of them.
>> I think that without such objectives we will never make any progress and we should.
>>
>> so what are the first 5% of packages that are not documented.
>>
>> Stef
>>
>>> The next step would be a Pareto classification, as it can be accepted (I hope) that SUnit has more history (and it is documented elsewhere, like PBE book) than other classes which even the name of it or its methods may be insufficient to arrive at for what is the class.
>>>
>>> We should create IRC meetings, sprints, etc. specially targeted to document these classes.
>>>
>>> my .019999...
>>>
>>> --
>>> Cesar Rabak
>>>
>>>
>>> Em 05/12/2010 20:07, Mariano Martinez Peck < [hidden email] > escreveu:
>>>
>>> On Sun, Dec 5, 2010 at 9:52 PM, Stéphane Ducasse <[hidden email]> wrote:
>>>
>>> Hi guys
>>>
>>> I decided that I will not integrate any code that is not documented in Pharo.
>>>
>>> I strongly suggest to remove from Pharo-dev packages whose classes are not commented.
>>>
>>>
>>> I think this is not a good idea...look this approx:
>>>
>>>
>>>
>>> | pharoCorePackages packagesDev nonCommentedClasses totalClasses |
>>> pharoCorePackages := #('MultilingualTests' 'Morphic' 'ToolBuilder-Kernel' 'PackageInfo' 'Polymorph-ToolBuilder' 'Network-Kernel' 'Network-Protocols' 'Compiler' 'System-Finalization' 'Settings-Graphics' 'Collections' 'Network-RemoteDirectory' 'Traits' 'Network-URI' 'Settings-Display' 'Collections-Abstract' 'Settings-Compiler' 'MonticelloMocks' 'ScriptLoader11' 'System-Digital Signatures' 'System-Localization' 'MenuRegistration' 'Polymorph-TaskbarIcons' 'Monticello' 'ToolBuilder-Morphic' 'MCDirtyPackage' 'Collections-Weak' 'Settings-Polymorph' 'Tests' 'HelpSystem-Core-Utilities' 'SUnit' 'Collections-Text' 'Compression' 'Morphic-MorphTreeWidget' 'HelpSystem-Core' 'ToolsTest' 'Gofer-Core' 'Gofer-Tests' 'Collections-Stack' 'FreeType' 'MonticelloConfigurations' 'Polymorph-Geometry' 'Collections-Support' 'SUnitGUI' 'HelpSystem-Core-Model' 'Tests-VM' 'System-Change Notification' 'System' 'Tests-ObjectsAsMethods' 'HostMenus' 'Network-MIME' 'Network-RFC822' 'VB-Regex' 'TrueType' 'Depr
>>> ecatedPreferences' 'System-Clipboard' 'System-Settings' 'MorphicTests' 'System-Serial Port' 'NetworkTests' 'Collections-Unordered' 'System-Changes' 'System-Object Storage' 'Collections-Traits' 'System-Platforms' 'Tests-PrimCallController' 'Morphic-TrueType' 'Multilingual' 'Graphics' 'Collections-Strings' 'KernelTests' 'System-FileRegistry' 'Tests-Bugs' 'ToolBuilder-SUnit' 'Tests-Release' 'Morphic-Balloon' 'Settings-Network' 'System-Applications' 'Polymorph-Tools-Diff' 'Settings-Tools' 'ScriptLoader' 'ST80' 'FreeTypeSubPixelAntiAliasing' 'Settings-Kernel' 'Settings-System' 'CompilerTests' 'System-Tools' 'System-Hashing' 'System-Download' 'Collections-Streams' 'Tests-SystemChangeNotification' 'GraphicsTests' 'Polymorph-Widgets' 'Kernel' 'Tools' 'Settings-FreeType' 'FreeTypeTests' 'Settings-Monticello' 'HelpSystem-Tests' 'Polymorph-EventEnhancements' 'System-Support' 'MonticelloGUI' 'System-FilePackage' 'System-Object Events' 'Announcements' 'System-Text' 'Exceptions' 'Network-
>>> UUID' 'System-Pools' 'FixUnderscores' 'HelpSystem-Core-UI' 'GraphicsResources' 'Files' 'Gofer' 'Network-MailSending' 'Collections-Arrayed' 'CollectionsTests' 'Balloon' 'Network-Url' 'Collections-Sequenceable' ).
>>> packagesDev := (PackageInfo allPackages
>>> collect: [:each | each packageName])
>>> difference: pharoCorePackages.
>>> nonCommentedClasses := packagesDev
>>> inject: 0
>>> into: [:sum :each | sum + (((PackageInfo named: each) classes
>>> select: [:aClass | aClass comment asString includesSubString: 'is xxxxxxxxx.']) size)].
>>> Transcript show: 'nonCommentedClasses: ', nonCommentedClasses asString.
>>>
>>> totalClasses :=  packagesDev inject: 0 into: [:sum :each | sum + (PackageInfo named: each) classes size ].
>>> Transcript show: 'totalClasses: ', totalClasses asString.
>>>
>>>
>>>
>>> Shows:
>>>
>>> nonCommentedClasses: 1116
>>> totalClasses: 1369
>>>
>>>
>>> I'm not sure that I will look at code or answer question to code that is not commented.
>>> We should change our mindset and it seems that we do not care, so we should take radical decisions:
>>> less changes, less progress, more comments.
>>>
>>> And for once I will not bash the past. Smalltalk was always with methods fully documented.
>>> We are just plain lazy and this is a shame.
>>>
>>> Stef
>>>
>>>
>>>
>>>
>>>
>>>
>>
>>
>
> --
> _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:
> Alexandre Bergel  http://www.bergel.eu
> ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
>
>
>
>
>
>
>

--
_,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:
Alexandre Bergel  http://www.bergel.eu
^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.






Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice for you

Stéphane Ducasse
In reply to this post by Sean P. DeNigris

On Dec 6, 2010, at 7:41 PM, Sean P. DeNigris wrote:

>
>
> laurent laffont wrote:
>>
>>> IMHO, before we take such a stance, we should have a package comment pane
>>> and encourage its use.  A complex package is probably best documented
>>> with a
>>> good high-level description and some type of example(s), which can take
>>> the
>>> form of do-its in a package comment.
>>
>> HelpSystem does this and is included in PharoCore. See
>> http://www.pharocasts.com/2010/09/document-with-helpsystem.html
>>
>
> What if the source pane in the browser showed the first page of the
> package's help when only a package name was selected?  

good first step!

> And there could be a
> shortcut/cataegory-list-menu-option to open the help browser on the
> package's help from the browser!
>
> Sean
> --
> View this message in context: http://forum.world.st/Comments-or-no-integration-a-simple-choice-for-you-tp3073643p3075057.html
> Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
>


Reply | Threaded
Open this post in threaded view
|

Re: Comments or no integration: a simple choice foryou

Stéphane Ducasse
In reply to this post by Alexandre Bergel
Yes good script.

Stef

On Dec 7, 2010, at 4:35 PM, Alexandre Bergel wrote:

> Indeed. We could also refine it further by identifying the most used classes for a representative sample of the Pharo ecosystem.
> It still says StandardFonts, SystemChangeNotifier, FreeTypeSettings, MCPackage, ... have to be commented
>
> Alexandre
>
>
> On 7 Dec 2010, at 12:29, Gary Chambers wrote:
>
>> Naturally, every method of a class references its own class as a literal...
>> Also, class-side methods not accounted for.
>>
>> Easy enough to change the script to higlight only external references:
>>
>> d := Dictionary new.
>> Smalltalk allClasses, (Smalltalk allClasses collect: [:cls | cls class]) do: [ :cls |
>> cls methods do: [:cm | (cm literals select: [:l | l isKindOf: Association ])
>> do: [:assoc |
>> (assoc value isBehavior and: [assoc value ~~ cls])
>>  ifTrue: [d at: assoc value put: (d at: assoc value ifAbsentPut: [0] ) + 1]]]].
>> associations := d associations asSortedCollection: [:a1 :a2 | a2 value < a1 value].
>> associations select: [:ass | ass key comment isNil or: [ass key comment isEmpty or: [ass key comment asString includesSubString: 'xxxxxx']]]
>>
>> Regards, Gary
>>
>> ----- Original Message ----- From: "Alexandre Bergel" <[hidden email]>
>> To: <[hidden email]>
>> Sent: Tuesday, December 07, 2010 2:53 PM
>> Subject: Re: [Pharo-project] Comments or no integration: a simple choice foryou
>>
>>
>> A small script that gives the most referenced classes that are not commented:
>> I run the test in an image with Moose and Spy.
>> -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
>> "Get the number of references per class"
>> d := Dictionary new.
>> Smalltalk allClasses do: [ :cls | cls methods do: [:cm | (cm literals select: [:l | l isKindOf: Association ])
>> do: [:assoc |
>> (assoc value isBehavior)
>> ifTrue: [d at: assoc value put: (d at: assoc value ifAbsentPut: [0] ) + 1]]]].
>> associations := d associations asSortedCollection: [:a1 :a2 | a2 value < a1 value].
>>
>> "Get the classes that are not commented"
>> associations select: [:ass | ass key comment isNil or: [ass key comment isEmpty or: [ass key comment asString includesSubString: 'xxxxxx']]]
>> -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
>>
>> The first 30 entries:
>> SortedCollectionTest->307
>> HeapTest->304
>> IntervalTest->250
>> DictionaryTest->192
>> BagTest->167
>> RxMatcherTest->166
>> PluggableTextMorph->149
>> MooseModel->144
>> UIThemeWatery2->132
>> SystemChangeNotifier->132
>> PPSmalltalkParserTests->129
>> FAMIXClassNavigationTest->128
>> PPJavaSyntax->128
>> PPSmalltalkGrammarTests->128
>> RBRefactoryTestDataApp->123
>> NSFileStream->118
>> NSRWBinaryOrTextStream->109
>> LogicalFont->109
>> NSMultiByteBinaryOrTextStream->108
>> UIThemeW2K->103
>> MCWorkingCopy->101
>> BrowserEnvironment->97
>> DemoSettingStyle->94
>> PPJavaLexiconTests->94
>> MCClassDefinition->93
>> NSAbstractInflateStream->92
>> MCWorkingCopyBrowser->91
>> NSCollectionStreamTest->91
>> GMMetaObject->91
>> ExceptionTester->90
>>
>>
>> Cheers,
>> Alexandre
>>
>>
>> On 7 Dec 2010, at 10:48, Stéphane Ducasse wrote:
>>
>>>> The good idae is to push and promote people to put class comments, but not to remove not commented classes from Dev, bacause otherise, you will need to remove 80% of the classes.
>>>
>>>
>>> So this is simple to start fixing some of them.
>>> I think that without such objectives we will never make any progress and we should.
>>>
>>> so what are the first 5% of packages that are not documented.
>>>
>>> Stef
>>>
>>>> The next step would be a Pareto classification, as it can be accepted (I hope) that SUnit has more history (and it is documented elsewhere, like PBE book) than other classes which even the name of it or its methods may be insufficient to arrive at for what is the class.
>>>>
>>>> We should create IRC meetings, sprints, etc. specially targeted to document these classes.
>>>>
>>>> my .019999...
>>>>
>>>> --
>>>> Cesar Rabak
>>>>
>>>>
>>>> Em 05/12/2010 20:07, Mariano Martinez Peck < [hidden email] > escreveu:
>>>>
>>>> On Sun, Dec 5, 2010 at 9:52 PM, Stéphane Ducasse <[hidden email]> wrote:
>>>>
>>>> Hi guys
>>>>
>>>> I decided that I will not integrate any code that is not documented in Pharo.
>>>>
>>>> I strongly suggest to remove from Pharo-dev packages whose classes are not commented.
>>>>
>>>>
>>>> I think this is not a good idea...look this approx:
>>>>
>>>>
>>>>
>>>> | pharoCorePackages packagesDev nonCommentedClasses totalClasses |
>>>> pharoCorePackages := #('MultilingualTests' 'Morphic' 'ToolBuilder-Kernel' 'PackageInfo' 'Polymorph-ToolBuilder' 'Network-Kernel' 'Network-Protocols' 'Compiler' 'System-Finalization' 'Settings-Graphics' 'Collections' 'Network-RemoteDirectory' 'Traits' 'Network-URI' 'Settings-Display' 'Collections-Abstract' 'Settings-Compiler' 'MonticelloMocks' 'ScriptLoader11' 'System-Digital Signatures' 'System-Localization' 'MenuRegistration' 'Polymorph-TaskbarIcons' 'Monticello' 'ToolBuilder-Morphic' 'MCDirtyPackage' 'Collections-Weak' 'Settings-Polymorph' 'Tests' 'HelpSystem-Core-Utilities' 'SUnit' 'Collections-Text' 'Compression' 'Morphic-MorphTreeWidget' 'HelpSystem-Core' 'ToolsTest' 'Gofer-Core' 'Gofer-Tests' 'Collections-Stack' 'FreeType' 'MonticelloConfigurations' 'Polymorph-Geometry' 'Collections-Support' 'SUnitGUI' 'HelpSystem-Core-Model' 'Tests-VM' 'System-Change Notification' 'System' 'Tests-ObjectsAsMethods' 'HostMenus' 'Network-MIME' 'Network-RFC822' 'VB-Regex' 'TrueType' 'Depr
>>>> ecatedPreferences' 'System-Clipboard' 'System-Settings' 'MorphicTests' 'System-Serial Port' 'NetworkTests' 'Collections-Unordered' 'System-Changes' 'System-Object Storage' 'Collections-Traits' 'System-Platforms' 'Tests-PrimCallController' 'Morphic-TrueType' 'Multilingual' 'Graphics' 'Collections-Strings' 'KernelTests' 'System-FileRegistry' 'Tests-Bugs' 'ToolBuilder-SUnit' 'Tests-Release' 'Morphic-Balloon' 'Settings-Network' 'System-Applications' 'Polymorph-Tools-Diff' 'Settings-Tools' 'ScriptLoader' 'ST80' 'FreeTypeSubPixelAntiAliasing' 'Settings-Kernel' 'Settings-System' 'CompilerTests' 'System-Tools' 'System-Hashing' 'System-Download' 'Collections-Streams' 'Tests-SystemChangeNotification' 'GraphicsTests' 'Polymorph-Widgets' 'Kernel' 'Tools' 'Settings-FreeType' 'FreeTypeTests' 'Settings-Monticello' 'HelpSystem-Tests' 'Polymorph-EventEnhancements' 'System-Support' 'MonticelloGUI' 'System-FilePackage' 'System-Object Events' 'Announcements' 'System-Text' 'Exceptions' 'Network-
>>>> UUID' 'System-Pools' 'FixUnderscores' 'HelpSystem-Core-UI' 'GraphicsResources' 'Files' 'Gofer' 'Network-MailSending' 'Collections-Arrayed' 'CollectionsTests' 'Balloon' 'Network-Url' 'Collections-Sequenceable' ).
>>>> packagesDev := (PackageInfo allPackages
>>>> collect: [:each | each packageName])
>>>> difference: pharoCorePackages.
>>>> nonCommentedClasses := packagesDev
>>>> inject: 0
>>>> into: [:sum :each | sum + (((PackageInfo named: each) classes
>>>> select: [:aClass | aClass comment asString includesSubString: 'is xxxxxxxxx.']) size)].
>>>> Transcript show: 'nonCommentedClasses: ', nonCommentedClasses asString.
>>>>
>>>> totalClasses :=  packagesDev inject: 0 into: [:sum :each | sum + (PackageInfo named: each) classes size ].
>>>> Transcript show: 'totalClasses: ', totalClasses asString.
>>>>
>>>>
>>>>
>>>> Shows:
>>>>
>>>> nonCommentedClasses: 1116
>>>> totalClasses: 1369
>>>>
>>>>
>>>> I'm not sure that I will look at code or answer question to code that is not commented.
>>>> We should change our mindset and it seems that we do not care, so we should take radical decisions:
>>>> less changes, less progress, more comments.
>>>>
>>>> And for once I will not bash the past. Smalltalk was always with methods fully documented.
>>>> We are just plain lazy and this is a shame.
>>>>
>>>> Stef
>>>>
>>>>
>>>>
>>>>
>>>>
>>>>
>>>
>>>
>>
>> --
>> _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:
>> Alexandre Bergel  http://www.bergel.eu
>> ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
>>
>>
>>
>>
>>
>>
>>
>
> --
> _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:
> Alexandre Bergel  http://www.bergel.eu
> ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
>
>
>
>
>
>