[Seaside] Re: Seaside and REST

[Andreas Raab]

Philippe Marschall wrote:
> We suck at documentation and getting started. We know that and are not
> proud about this. We know the store example sucks. What would help are
> easy ways to turn mails like this into useful documentation. And of
> course if people help with documentation ...

One of the things that I have done in the past is to, instead of 
responding on-list, work information like this directly in a Wiki that 
you refer people to. This has two advantages: First, the information is 
preserved automatically, second, after a while people learn that this is 
a good place to go look for answers.

[--- big snip; wearing my flame-proof suit now ---]

BTW, I can tell you in numbers how much Seaside sucks for documentation 
- I noticed the apparent lack of any comments in so much of the code so 
I wrote a little analysis tool which looks at both class and method 
comments, ran this over my image, and took out everything that is less 
than 50 classes. The result (in alphabetical order so as not to 
embarrass you right away ;-) is this:

Category	Classes Comments    %	Methods Comments   %
Chat-*		50	12	24.00	584	151	25.85
Collections-*	86	71	82.55	2009	1200	59.73
Croquet-*	254	225	88.58	4599	1857	40.37
Games-*		95	43	45.26	1114	198	17.77
Graphics-*	57	46	80.70	1827	1085	59.38
Kernel-*	81	72	88.88	3171	2172	68.49
Magritte-*	214	83	38.78	1742	117	6.71
Monticello-*	135	10	7.40	1502	70	4.66
Morphic-*	419	255	60.85	10546	5037	47.76
Multilingual-*	85	37	43.52	715	182	25.45
Network-*	148	94	63.51	1512	728	48.14
Pier-*		157	46	29.29	1227	154	12.55
Qwaq-*		235	204	86.80	3746	2057	54.91
QwaqDemo-*	89	80	89.88	967	488	50.46
Scriptaculous-*	74	3	4.05	690	172	24.92
Seaside-*	297	40	13.46	2809	126	4.48
Sound-*		71	39	54.92	1252	615	49.12
ST80-*		72	58	80.55	1447	1030	71.18
Swazoo-*	81	1	1.23	718	45	6.26
System-*	123	72	58.53	2125	1218	57.31
Tools-*		60	42	70.00	1550	969	62.51
Tweak-*		563	281	49.91	9432	4743	50.28
VMMaker-*	93	71	76.34	3230	1488	46.06

If you sort this a little (I'd love to use dabbledb for this but I 
haven't figured it out yet ;-) you'll find that Seaside scores the 4th 
to last rank when looking at percentage of classes commented, and 
rock-bottom for percentage of methods commented. Ouch.

[BTW, the best commented web package is HV2 but it is so small (44 
classes) that it isn't listed here. It has 72% class and 53% method 
comment coverage which is a fair bit above average]

The code for the above analysis is attached.

Cheers,
   - Andreas
-------------- next part --------------
'From Croquet1.0beta of 11 April 2006 [latest update: #1] on 29 March 2007 at 4:49:45 pm'!

!SystemDictionary methodsFor: 'miscellaneous' stamp: 'ar 3/29/2007 16:49'!
commentCoverageFor: pattern on: stream
	"Smalltalk commentCoverageFor: 'Kernel-*' on: Transcript"
	"[
		UIManager default edit:(String streamContents:[:s|
			(SystemOrganization categories collect:[:cat| cat copyUpTo: $-]) asSet asArray sort 
				do:[:cat| Smalltalk commentCoverageFor: cat,'-*' on: s]])
			label: 'Comment coverage'.
	]"
	| cls allClasses allMethods classesCommented methodsCommented |
	allClasses := classesCommented := 0.
	allMethods := methodsCommented := 0.
	Utilities informUserDuring:[:bar|
	(SystemOrganization categoriesMatching: pattern) do:[:cat|
		(SystemOrganization listAtCategoryNamed: cat) do:[:clsName|
			bar value: clsName.
			cls := Smalltalk classNamed: clsName.
			allClasses := allClasses + 1.
			(cls organization classComment isEmpty) 
				ifFalse:[classesCommented := classesCommented + 1].
			cls selectors do:[:sel|
				allMethods := allMethods + 1.
				(cls firstPrecodeCommentFor: sel)
					ifNotNil:[methodsCommented := methodsCommented+1].
			].
		].
	].
	].
	stream cr; nextPutAll: pattern.
	stream tab; tab; print: allClasses.
	stream tab; tab; print: classesCommented.
	stream tab; tab; print: (100.0 * classesCommented / (allClasses max: 1) truncateTo: 0.01).
	stream tab; tab; print: allMethods.
	stream tab; tab; print: methodsCommented.
	stream tab; tab; print: (100.0 * methodsCommented / (allMethods max: 1) truncateTo: 0.01).
	stream flush. "in case of Transcript"
! !