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: [email protected] [[email protected]] On Behalf Of Stéphane Ducasse [[email protected]] Sent: Sunday, December 05, 2010 3:52 PM To: [email protected] 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
