Class comments!?

goran.krampe at bluefish.se goran.krampe at bluefish.se
Tue Oct 19 15:08:11 UTC 2004


Hi!

Well, this is turning into an addiction - can't help replying. :)

lex at cc.gatech.edu wrote:
> Hey Goran, let's do indeed be careful not to drift down a slippery
> slope.  Quality does matter.

Good.
 
> Your water analogy seems to show our difference nicely.  You want a high
> *percentage* of good, commented code.  I want a high *volume* of good
> code.  I think that uncommented code can still be pretty darned good,
> and thus that usually:

I don't think we want different things, instead I think you are making a
conclusion that is false regarding what I want, see below.
 
> 	X + (good, uncommented code)  >  X
> 	
> A decent way to getting a higher volume of commented code is to put
> uncommented code in there and thus make it easy for people to contribute.

Eh... What? That is probably the silliest thing I have heard in this
thread. Really. ;)
The *author* of the code should write the comments. As Richard has so
eloquently (as always) explained - it is about the author expressing the
*intentions* of the class etc.

And also - what you are proposing (?) is AFAICT what we have been doing
over the years. And it hasn't really worked, has it? I have just
collected some stats (code below and printout) on 3.5, 3.6, 3.7 and
current 3.8. If you look at percentage of classes without comments it
was about 43%->40%->37% (positive trend? hard to say, depends) and now
42% (oops). Of course, 3.5 to 3.6 removed a LOT of classes so more
analysis is needed to get the whole picture.

Anyway, we *have* about 40% uncommented classes and I can't see people
rushing in to put comments on *those*.

> If we reject code then we spoil the open source process we have going
> and make it hard for people to fix (comment) the code.  But of course,
> putting in uncommented code reduces the *percentage* of commented code,
> perhaps indefinitely.

Note that having a rule saying that all classes should have a comment
(no matter how small) is IMHO not a rule that will reject code. I
honestly believe that the author would take the little time needed and
just fix it.
 
> I agree the *percentage* of good code would be important if Squeak were at
> a stage that it is worth picking it up and studying it.  However, I think

*We* are studying it every day!!! Your reasoning strikes me as truly
odd.

> Squeak is at a much earlier stage right now.  It is likely that huge
> chunks of it will be tossed entirely before we get within reach of the
> next system that is really a crystaline beauty worthy of study.  In the
> meantime, functionality is extremely worthwhile, because it lets people
> do experiments.
> 
> In short, why would the *percentage* of clear code be more important
> than the *volume* of clear code?

Well, IMHO it is a measurement of the quality of the code base. And as I
said before - it would seem very, very strange to me if the authors that
we trust to write code that goes into the image would decide to NOT
write these class comments and thus keep their contributions outside of
the image.

Again I am amazed at the arguments being put forward. Both disappointing
and discouraging. But I should have learned the last time.

> -Lex

regards, Göran

--------------------------
-----------------------------
| categoryPatterns uglies goodies prefix extractBlock printBlock
listBlock ugliesSize goodiesSize |
uglies _ Dictionary new.
goodies _ Dictionary new.
categoryPatterns := #('*').
categoryPatterns do: [:pat |
	(SystemOrganization categoriesMatching: pat) do: [:cat |
		prefix _ (cat findTokens: '-') first.
		(SystemOrganization superclassOrder: cat) do: [:c |
			uglies at: prefix ifAbsent: [uglies at: prefix put: OrderedCollection
new.
				goodies at: prefix put: OrderedCollection new].
			selected _ c theNonMetaClass organization classComment isEmpty
				ifTrue:[uglies] ifFalse: [goodies].
			(selected at: prefix) add: c name]]].
extractBlock _ [:c | | good bad|
	good _ (goodies at: c) size.
	bad _ (uglies at: c) size.
	{ c.  bad. bad+good.  ((bad / (good+bad)) asFloat * 100) truncated}].
printBlock _ [:c :bad :total :percent | 
		Transcript nextPutAll: c; nextPutAll: ': ';nextPutAll: bad
printString;
			nextPutAll: ' (',total printString , ') ',percent printString, '%';
cr].
listBlock _ [:sortBlock |
	((uglies keys collect: [:c | extractBlock value: c])
asOrderedCollection sortBy: sortBlock)
		do: [:values |
			values second > 0 ifTrue: [
			printBlock value: values first value: values second value: values
third value: values fourth]]].

Transcript clear; nextPutAll: 'Packages (category prefix) sorted by
bad';cr.
listBlock value: [:a :b | a second > b second]. "Sort by number of bads"

Transcript cr; nextPutAll: 'Packages (category prefix) sorted
alphabetically:';cr.
listBlock value: [:a :b | a first < b first].  "Sort by category prefix"

Transcript cr; nextPutAll: 'Packages (category prefix) sorted by
percents bad';cr.
listBlock value: [:a :b | a last > b last].  "Sort by percent"

Transcript cr; nextPutAll: 'Total';cr.
ugliesSize _ 0.
goodiesSize _ 0.
uglies keysAndValuesDo: [:p :oc |
	ugliesSize _ ugliesSize + oc size].
goodies keysAndValuesDo: [:p :oc |
	goodiesSize _ goodiesSize + oc size].
percent _ ((ugliesSize / (goodiesSize+ugliesSize)) asFloat * 100)
truncated.
Transcript nextPutAll: ugliesSize printString, ' (',(goodiesSize +
ugliesSize) printString , ') ',percent printString, '%'; cr.
Transcript flush
--------------------------------
3.5
Packages (category prefix) sorted by bad
Morphic: 267 (492) 54%
Balloon3D: 90 (185) 48%
Network: 66 (191) 34%
System: 55 (156) 35%
Balloon: 53 (65) 81%
VMConstruction: 50 (109) 45%
Sound: 32 (70) 45%
XML: 22 (23) 95%
Tools: 20 (82) 24%
Speech: 20 (40) 50%
FFI: 17 (27) 62%
Collections: 16 (81) 19%
Protocols: 15 (27) 55%
Kernel: 14 (71) 19%
Graphics: 11 (69) 15%
ST80: 11 (52) 21%
StarSqueak: 11 (15) 73%
SUnit: 7 (15) 46%
Genie: 5 (32) 15%
SCAN: 1 (3) 33%
Framework: 1 (1) 100%

Packages (category prefix) sorted alphabetically:
Balloon: 53 (65) 81%
Balloon3D: 90 (185) 48%
Collections: 16 (81) 19%
FFI: 17 (27) 62%
Framework: 1 (1) 100%
Genie: 5 (32) 15%
Graphics: 11 (69) 15%
Kernel: 14 (71) 19%
Morphic: 267 (492) 54%
Network: 66 (191) 34%
Protocols: 15 (27) 55%
SCAN: 1 (3) 33%
ST80: 11 (52) 21%
SUnit: 7 (15) 46%
Sound: 32 (70) 45%
Speech: 20 (40) 50%
StarSqueak: 11 (15) 73%
System: 55 (156) 35%
Tools: 20 (82) 24%
VMConstruction: 50 (109) 45%
XML: 22 (23) 95%

Packages (category prefix) sorted by
percents bad
Framework: 1 (1) 100%
XML: 22 (23) 95%
Balloon: 53 (65) 81%
StarSqueak: 11 (15) 73%
FFI: 17 (27) 62%
Protocols: 15 (27) 55%
Morphic: 267 (492) 54%
Speech: 20 (40) 50%
Balloon3D: 90 (185) 48%
SUnit: 7 (15) 46%
VMConstruction: 50 (109) 45%
Sound: 32 (70) 45%
System: 55 (156) 35%
Network: 66 (191) 34%
SCAN: 1 (3) 33%
Tools: 20 (82) 24%
ST80: 11 (52) 21%
Kernel: 14 (71) 19%
Collections: 16 (81) 19%
Genie: 5 (32) 15%
Graphics: 11 (69) 15%

Total
784 (1811) 43%
------------------------
3.6
Packages (category prefix) sorted by bad
Morphic: 217 (423) 51%
System: 55 (161) 34%
Balloon: 52 (64) 81%
Sound: 31 (70) 44%
XML: 22 (23) 95%
Speech: 21 (41) 51%
Tools: 19 (81) 23%
FFI: 18 (28) 64%
Collections: 15 (79) 18%
Protocols: 15 (27) 55%
Network: 12 (82) 14%
ST80: 11 (52) 21%
StarSqueak: 11 (14) 78%
Kernel: 11 (71) 15%
Graphics: 8 (53) 15%
Genie: 5 (31) 16%
SUnit: 4 (9) 44%
EToy: 3 (3) 100%
PackageInfo: 2 (3) 66%
Multilingual: 1 (2) 50%
Squeak: 1 (1) 100%
SM: 1 (13) 7%
Framework: 1 (1) 100%

Packages (category prefix) sorted
alphabetically:
Balloon: 52 (64) 81%
Collections: 15 (79) 18%
EToy: 3 (3) 100%
FFI: 18 (28) 64%
Framework: 1 (1) 100%
Genie: 5 (31) 16%
Graphics: 8 (53) 15%
Kernel: 11 (71) 15%
Morphic: 217 (423) 51%
Multilingual: 1 (2) 50%
Network: 12 (82) 14%
PackageInfo: 2 (3) 66%
Protocols: 15 (27) 55%
SM: 1 (13) 7%
ST80: 11 (52) 21%
SUnit: 4 (9) 44%
Sound: 31 (70) 44%
Speech: 21 (41) 51%
Squeak: 1 (1) 100%
StarSqueak: 11 (14) 78%
System: 55 (161) 34%
Tools: 19 (81) 23%
XML: 22 (23) 95%

Packages (category prefix) sorted by
percents bad
Framework: 1 (1) 100%
EToy: 3 (3) 100%
Squeak: 1 (1) 100%
XML: 22 (23) 95%
Balloon: 52 (64) 81%
StarSqueak: 11 (14) 78%
PackageInfo: 2 (3) 66%
FFI: 18 (28) 64%
Protocols: 15 (27) 55%
Morphic: 217 (423) 51%
Speech: 21 (41) 51%
Multilingual: 1 (2) 50%
SUnit: 4 (9) 44%
Sound: 31 (70) 44%
System: 55 (161) 34%
Tools: 19 (81) 23%
ST80: 11 (52) 21%
Collections: 15 (79) 18%
Genie: 5 (31) 16%
Graphics: 8 (53) 15%
Kernel: 11 (71) 15%
Network: 12 (82) 14%
SM: 1 (13) 7%

Total
536 (1338) 40%
-------------------------
3.7
Packages (category prefix) sorted by bad
Morphic: 186 (409) 45%
System: 76 (196) 38%
Sound: 32 (71) 45%
Kernel: 32 (131) 24%
Balloon: 30 (64) 46%
Collections: 24 (98) 24%
Tests: 23 (35) 65%
Tools: 23 (93) 24%
Speech: 21 (41) 51%
FFI: 18 (28) 64%
Nebraska: 15 (36) 41%
Protocols: 15 (27) 55%
Graphics: 12 (58) 20%
ST80: 12 (55) 21%
StarSqueak: 11 (14) 78%
Network: 9 (67) 13%
Exceptions: 8 (8) 100%
SUnit: 8 (15) 53%
Babel: 8 (8) 100%
EToy: 3 (3) 100%
SMLoader: 3 (4) 75%
PackageInfo: 3 (4) 75%
SMBase: 3 (24) 12%
UserObjects: 2 (2) 100%
Compiler: 1 (23) 4%
Movies: 1 (14) 7%
MCInstaller: 1 (1) 100%
Squeak: 1 (1) 100%
Multilingual: 1 (2) 50%
Framework: 1 (1) 100%

Packages (category prefix) sorted
alphabetically:
Babel: 8 (8) 100%
Balloon: 30 (64) 46%
Collections: 24 (98) 24%
Compiler: 1 (23) 4%
EToy: 3 (3) 100%
Exceptions: 8 (8) 100%
FFI: 18 (28) 64%
Framework: 1 (1) 100%
Graphics: 12 (58) 20%
Kernel: 32 (131) 24%
MCInstaller: 1 (1) 100%
Morphic: 186 (409) 45%
Movies: 1 (14) 7%
Multilingual: 1 (2) 50%
Nebraska: 15 (36) 41%
Network: 9 (67) 13%
PackageInfo: 3 (4) 75%
Protocols: 15 (27) 55%
SMBase: 3 (24) 12%
SMLoader: 3 (4) 75%
ST80: 12 (55) 21%
SUnit: 8 (15) 53%
Sound: 32 (71) 45%
Speech: 21 (41) 51%
Squeak: 1 (1) 100%
StarSqueak: 11 (14) 78%
System: 76 (196) 38%
Tests: 23 (35) 65%
Tools: 23 (93) 24%
UserObjects: 2 (2) 100%

Packages (category prefix) sorted by
percents bad
EToy: 3 (3) 100%
Babel: 8 (8) 100%
UserObjects: 2 (2) 100%
Exceptions: 8 (8) 100%
Framework: 1 (1) 100%
Squeak: 1 (1) 100%
MCInstaller: 1 (1) 100%
StarSqueak: 11 (14) 78%
PackageInfo: 3 (4) 75%
SMLoader: 3 (4) 75%
Tests: 23 (35) 65%
FFI: 18 (28) 64%
Protocols: 15 (27) 55%
SUnit: 8 (15) 53%
Speech: 21 (41) 51%
Multilingual: 1 (2) 50%
Balloon: 30 (64) 46%
Sound: 32 (71) 45%
Morphic: 186 (409) 45%
Nebraska: 15 (36) 41%
System: 76 (196) 38%
Collections: 24 (98) 24%
Tools: 23 (93) 24%
Kernel: 32 (131) 24%
ST80: 12 (55) 21%
Graphics: 12 (58) 20%
Network: 9 (67) 13%
SMBase: 3 (24) 12%
Movies: 1 (14) 7%
Compiler: 1 (23) 4%

Total
583 (1544) 37%
----------------------
3.8
Packages (category prefix) sorted by bad
Morphic: 191 (422) 45%
Multilingual: 79 (80) 98%
System: 79 (209) 37%
Compiler: 40 (42) 95%
Sound: 32 (70) 45%
Kernel: 32 (136) 23%
Balloon: 30 (64) 46%
Collections: 26 (102) 25%
Tests: 24 (36) 66%
Tools: 23 (95) 24%
Speech: 21 (41) 51%
FFI: 18 (28) 64%
Protocols: 15 (27) 55%
Graphics: 15 (62) 24%
Nebraska: 15 (36) 41%
ST80: 12 (55) 21%
SUnit: 11 (18) 61%
StarSqueak: 11 (14) 78%
Network: 9 (67) 13%
Exceptions: 8 (8) 100%
EToy: 3 (3) 100%
SMLoader: 3 (4) 75%
PackageInfo: 3 (4) 75%
SMBase: 3 (24) 12%
Squeak: 1 (1) 100%
Movies: 1 (14) 7%
UserObjects: 1 (1) 100%
Framework: 1 (1) 100%
MCInstaller: 1 (1) 100%

Packages (category prefix) sorted
alphabetically:
Balloon: 30 (64) 46%
Collections: 26 (102) 25%
Compiler: 40 (42) 95%
EToy: 3 (3) 100%
Exceptions: 8 (8) 100%
FFI: 18 (28) 64%
Framework: 1 (1) 100%
Graphics: 15 (62) 24%
Kernel: 32 (136) 23%
MCInstaller: 1 (1) 100%
Morphic: 191 (422) 45%
Movies: 1 (14) 7%
Multilingual: 79 (80) 98%
Nebraska: 15 (36) 41%
Network: 9 (67) 13%
PackageInfo: 3 (4) 75%
Protocols: 15 (27) 55%
SMBase: 3 (24) 12%
SMLoader: 3 (4) 75%
ST80: 12 (55) 21%
SUnit: 11 (18) 61%
Sound: 32 (70) 45%
Speech: 21 (41) 51%
Squeak: 1 (1) 100%
StarSqueak: 11 (14) 78%
System: 79 (209) 37%
Tests: 24 (36) 66%
Tools: 23 (95) 24%
UserObjects: 1 (1) 100%

Packages (category prefix) sorted by
percents bad
Framework: 1 (1) 100%
UserObjects: 1 (1) 100%
EToy: 3 (3) 100%
Squeak: 1 (1) 100%
Exceptions: 8 (8) 100%
MCInstaller: 1 (1) 100%
Multilingual: 79 (80) 98%
Compiler: 40 (42) 95%
StarSqueak: 11 (14) 78%
SMLoader: 3 (4) 75%
PackageInfo: 3 (4) 75%
Tests: 24 (36) 66%
FFI: 18 (28) 64%
SUnit: 11 (18) 61%
Protocols: 15 (27) 55%
Speech: 21 (41) 51%
Balloon: 30 (64) 46%
Morphic: 191 (422) 45%
Sound: 32 (70) 45%
Nebraska: 15 (36) 41%
System: 79 (209) 37%
Collections: 26 (102) 25%
Tools: 23 (95) 24%
Graphics: 15 (62) 24%
Kernel: 32 (136) 23%
ST80: 12 (55) 21%
Network: 9 (67) 13%
SMBase: 3 (24) 12%
Movies: 1 (14) 7%

Total
708 (1679) 42%



More information about the Squeak-dev mailing list