On Sun, Dec 5, 2010 at 10:10 PM, Schwab,Wilhelm K <[email protected]>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: [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 > >
