Hey Goran, let's do indeed be careful not to drift down a slippery slope. Quality does matter.
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:
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. 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.
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 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?
-Lex
I have been reading this thread with interest, as our team has a similar split on comments.
We have a code base that is between 2 and 7 years old, and has seen contributions from about 7 primary developers.
While there are places that have pretty good comment coverage (class and method comments). There are whole chunks that have little or no comments. Those areas that have no comments also almost universally have no developer level documentation. The rationale is always the same: "the comments lie so why write them", or "who has time for that", or "just read the code to see what it does".
As commented ;-) on this thread, the point (as I see it) of comments or any documentation is not to say what the code does, but why it does it, and to give the reader of the code enough context to understand the code he/she is reading without having first to understand the whole thing in detail. It is true that before making changes a programmer SHOULD understand the code in detail, but getting started on a whole new block of code is daunting without some good context and english description of how the pieces fit together and their roles in the whole endeavor.
This was driven home recently when the author / maintainer of a piece of our product was unavailable and I was asked to step in and make an enhancement. Without comments (or documentation) to get started I was unable to be effective on short notice, and the task was put on hold waiting for the original developer to have time. But, in those cases where the original developer is never going to have time (key person or just gone), the lack of contextual documentation is a huge risk to any organization.
I favor comments over documentation in some other repository because it increases the chance that the next poor sod to work on my code will be able to find it. The word documents prepared at various points and placed under CM are never as easy to locate as comments in the code.
But the issue is not when will Squeak be worthy of study. If you can not maintain it and refine it, it will never get there. As an old time Smalltalker I hope it gets there, so I also hope that you do take the time to make it maintainable, otherwise it will be a large research effort that will collapse in on itself like so many others.
Just my $0.02 on a subject of recent concern.
Michael
On Oct 18, 2004, at 8:18 PM, lex@cc.gatech.edu wrote:
Hey Goran, let's do indeed be careful not to drift down a slippery slope. Quality does matter.
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:
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. 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.
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 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?
-Lex
On Mon, 18 Oct 2004 16:24:51 -0700, Michael Latta lattam@mac.com wrote:
I favor comments over documentation in some other repository because it increases the chance that the next poor sod to work on my code will be able to find it. The word documents prepared at various points and placed under CM are never as easy to locate as comments in the code.
I think what's excited me about this discussion is that I can see a comment system that could actually work, if it were externally and internally synchronous. Externally, for clients of the system who want to use the objects without having to go through the code, and internally for those who want or need to get into them. Also, the notion of an OO comment system intrigues me, where comments are inherited.
I agree. It would be really cool to see what could be done to add a real documentation system to the image, making use of everything the tools know about the code, and can infer. As you say there should be 2 perspectives supported, those that want to use a class or group of classes, and those that are working on a class or group of classes.
Michael
On Oct 18, 2004, at 4:36 PM, Blake wrote:
On Mon, 18 Oct 2004 16:24:51 -0700, Michael Latta lattam@mac.com wrote:
I favor comments over documentation in some other repository because it increases the chance that the next poor sod to work on my code will be able to find it. The word documents prepared at various points and placed under CM are never as easy to locate as comments in the code.
I think what's excited me about this discussion is that I can see a comment system that could actually work, if it were externally and internally synchronous. Externally, for clients of the system who want to use the objects without having to go through the code, and internally for those who want or need to get into them. Also, the notion of an OO comment system intrigues me, where comments are inherited.
Blake wrote:
On Mon, 18 Oct 2004 16:24:51 -0700, Michael Latta lattam@mac.com wrote:
I favor comments over documentation in some other repository because it increases the chance that the next poor sod to work on my code will be able to find it. The word documents prepared at various points and placed under CM are never as easy to locate as comments in the code.
I think what's excited me about this discussion is that I can see a comment system that could actually work, if it were externally and internally synchronous. Externally, for clients of the system who want to use the objects without having to go through the code, and internally for those who want or need to get into them. Also, the notion of an OO comment system intrigues me, where comments are inherited.
Hi Blake,
You might enjoy studying a documentation feature of Eiffel called 'short form'. The Eiffel programming language has a form of executable OO-documentation that is inherited.
This OO-documentation is part of the source code but can easily be extracted by tools to show only the documentation of each class. A bit like JavaDoc, but richer. This extracted form is called 'short form'.
But the really cool part is that you can turn on a compiler switch and have the executable documentation checked, at runtime, against the actual code and get warned if the code and the executable documentation disagree in any way.
It's common for Eiffel developers to run their code with the compiler switches set to run most, or all, of the checks. Thus, when they trust their 'short form' documentation, they have a good reason to do so.
Cheers,
Peter
On Tue, 26 Oct 2004 09:42:10 +0200, Peter van Rooijen peter@vanrooijen.com wrote:
You might enjoy studying a documentation feature of Eiffel called 'short form'. The Eiffel programming language has a form of executable OO-documentation that is inherited.
I remember that! I was going to do a series of articles on Eiffel--ooh, ten years ago now. Loved it as a language, but sort of lost interest when it took Meyer and Co. so long to come up with anything, and what they did have at first seemed so bug-ridden.
Not to cast aspersions, it was just disappointing after reading all the great stuff about programming-by-contract and how robust it was supposed to make everything.
But the really cool part is that you can turn on a compiler switch and have the executable documentation checked, at runtime, against the actual code and get warned if the code and the executable documentation disagree in any way.
Yeah, I noticed a lot of stuff I first read about in Meyer's Eiffel books made its way into C++.
It's common for Eiffel developers to run their code with the compiler switches set to run most, or all, of the checks. Thus, when they trust their 'short form' documentation, they have a good reason to do so.
Sounds like the concept has been greatly refined since I read about it. I may have to check it out again. It had a lot going for it.
Lex writes:
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.
Heh, one of the big motivators for my current minimization work was being brutally confronted with this fact, the last time I taught a Squeak class. :)
I think making (Squeak/Smalltalk/anything-pretty-please!) into such a system is the highest priority.
-C
p.s.
Just want to point out that Michael Latta and I are in fact different people, and perhaps of some distant relation, but one that I haven't figured out yet. Greetings. :)
-- Craig Latta improvisational musical informaticist craig@netjam.org www.netjam.org [|] Proceed for Truth!
On Mon, Oct 18, 2004 at 11:18:44PM -0400, lex@cc.gatech.edu wrote:
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.
A sufficient quantity of poor quality stuff will somehow result in enough accumulated stuff that the sediment will settle to a level that amounts to adequate quality?
Might appeal to a catfish I suppose.
Hi!
Well, this is turning into an addiction - can't help replying. :)
lex@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%
goran.krampe@bluefish.se wrote:
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. ;)
It is an expression that volume matters. "+" is combining two globs of code. ">" means I like the left side better than the right. You would not consider this to be a true formula in all cases, but I would.
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.
Have you tried counting the *number* of *commented* classes? That has surely increased over the years. I really don't care that the percentage has gone down. Truly. So what if it has?
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.-
Well what is it then? If it's just a statement of what we would like, then I am pretty well agreeing with you. It's the rule part that bothers me. We have enough barriers and enough load on the harvesting process already.
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.
Well then please try to see where I am coming from. I don't know how better to express it than the difference between percentage and volume of nice code.
To try and get concrete again, I am suggesting that we generally include code into the image at an early stage, if the image is where it belongs, so that we can use the standard open-source approach and let everyone start playing with it. If there is some other way to make open source work, e.g. by sticking it on SqueakMap, then that would be fine, too, so long as it's really an optional package that isn't supposed to be in the image.
I really dislike the idea that the author is supposed to perfect the code before releasing it to play with. Squeak is a work in progress.
-Lex
Hi Lex!
As usual we talk around each other :), or at least I hope we do.
lex@cc.gatech.edu wrote:
goran.krampe@bluefish.se wrote:
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. ;)
It is an expression that volume matters. "+" is combining two globs of code. ">" means I like the left side better than the right. You would not consider this to be a true formula in all cases, but I would.
I wasn't commenting on your formula - I was commenting on the paragraph. Since I really don't believe the rule would leave good code outside of the image the formula makes no sense.
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.
Have you tried counting the *number* of *commented* classes? That has surely increased over the years. I really don't care that the percentage has gone down. Truly. So what if it has?
I intend to make a more detailed analysis, and since we also have removed classes from the image I wouldn't be so certain that the number of commented classes has increased. But why don't you care about the ratio? If we are getting a larger and larger base image (well, 3.5 -> 3.6 made it smaller, but then it has increased steadily) that is less and less commented - I consider that to be a problem. And please - remember that we are talking about the *base image* here.
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.-
Well what is it then? If it's just a statement of what we would like, then I am pretty well agreeing with you. It's the rule part that bothers me. We have enough barriers and enough load on the harvesting process already.
What I meant is that such a rule would IMHO not in practice make code rejected. I instead think it would make sure the code got at least minimally commented before going in.
I mean, we are pushing *new* classes into the *base* image here! Stuff that everyone relies on. We aren't talking about packages on SM. Normally we don't push 80 classes into the base image, do we? So why are you having such a problem with accepting this rule? Again, it *amazes* me. And also, remember that I am not proposing any rule about the comments - they can be short oneliners *if the author thinks that is enough*.
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.
Well then please try to see where I am coming from. I don't know how better to express it than the difference between percentage and volume of nice code.
What do you mean? You say that we are not at a stage where it is "worth picking it up and study it". I responded that hey, we study it every day!! Everyone trying to understand a new piece of the base image reads the class comments! Or at least they should, I have heard at least one person denying reading them - but he is most probably in the minority.
Anyway, then you responded with... what?
To try and get concrete again, I am suggesting that we generally include code into the image at an early stage, if the image is where it belongs, so that we can use the standard open-source approach and let everyone start playing with it. If there is some other way to make open source
Of course we do - but I say with the additional rule that the *author* introducing *new* classes (doesn't happen very often, and when it does they are generally few) includes a *minimal* class comment. Now... what is so terrible with that?
I am really not interested in talking about this anymore, I am simply out of breath.
work, e.g. by sticking it on SqueakMap, then that would be fine, too, so long as it's really an optional package that isn't supposed to be in the image.
I really dislike the idea that the author is supposed to perfect the code before releasing it to play with. Squeak is a work in progress.
Who the *hell* have said "perfect the code"?! I have said "include a damn single line class comment in new classes in the base image!!!". That is all. It is trivial. It is simple.
-Lex
regards, Göran
On Tue, 19 Oct 2004 19:15:54 -0400 , lex@cc.gatech.edu said:
goran.krampe@bluefish.se wrote:
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.
Have you tried counting the *number* of *commented* classes? That has surely increased over the years.
Well, depends on what you're counting. Probably the number of commented classes in the Full distribution? (I think Goran was counting Basic. Full is probably more appropriate.) I agree that we want to increase the total volume of quality Squeak code, but by this I would mean all Squeak apps (such as Seaside, etc.) some of which may not be included in Full. In other words, we want to increase the size of the community creating quality Squeak code, too. The more the better, basically.
But I'm not sure if that applies to the Full distribution... it would probably be good to add more stuff to Full, but not at a limitless rate.
Anyway, I see what you're saying... the total number of commented classes has not likely gone down, because that would mean that people are either removing comments from exiting classes, or replacing old commented classes with new uncommented ones, which is probably relatively rare.
I really don't care that the percentage has gone down. Truly. So what if it has?
I still think it's generally bad if the percentage has gone down. The burden of writing comments at the class level (as opposed to method level) just isn't that great, compared to the benefits, even if Squeak is still evolving and a bit crufty.
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.-
Well what is it then? If it's just a statement of what we would like, then I am pretty well agreeing with you. It's the rule part that bothers me. We have enough barriers and enough load on the harvesting process already.
I don't think the rate of harvesting would be significantly slowed by requiring class comments. IMHO the slowness of harvesting has had more to do with how many people have had access to the update stream and other issues.
Anyway, I've been thinking we should add something to the update broadcasting mechanism so that it checks for the existence of class comments and a few other basic things such as a changeset preamble, method initials/timestamps, and no linefeeds. (Actually I think it already checks for linefeeds.) So then I guess class comments would become a hard "rule". :)
The update broadcasting mechanism should make it as easy as possible to fix these on the spot, by direct prompting. Fixing linefeeds is easy. Adding method initials should be doable... the person broadcasting should know who the author is and be able to enter the missing initials. The broadcaster should also know enough about the basic intent of the changeset to enter a short preamble on the spot if forced to.
With class comments, the broadcaster could be prompted to fill in a missing comment. Of course, this is a problem if the broadcaster is not the author, although now that we're adding update-access for more people, quite often the broadcaster will be the author. But if not, hrmmmm, the broadcaster could either: 1. Go tell the author to add comments 2. Fill in the comment with something like "Comment to be added soon by John Doe and Janie Jones (the authors)". (There could be a prompt to fill in all empty class comments with this phrase, in extreme cases like 80 missing class comments with m17n.)
Anyway, I want to add this stuff soon to the broadcasting mechanism. Maybe I'll leave the class comment enforcement out at first.
Ideally, these checks could also happen further "upstream"... there could be a simple changeset verifier utility that does these checks that anyone could use. Anyone posting an [enh]/[fix] with intent to be included in Full would be encouraged to make sure it passed the verifier first.
Of course the verifier should only do the really must-have checks. In theory it could get into doing SLint checks and that sort of thing, but then that might actually slow the process down a bit too much. :)
- Doug
lex@cc.gatech.edu wrote:
goran.krampe@bluefish.se wrote:
X + (good, uncommented code) > X
Eh... What? That is probably the silliest thing I have heard in this thread. Really. ;)
It is an expression that volume matters. "+" is combining two globs of code. ">" means I like the left side better than the right. You would not consider this to be a true formula in all cases, but I would.
Well, yes, the volume of *good* code matters. Without question, however, a little comment can be a big (huge?) help in deciding whether the submitted code is good or not in the first place. I don't think anyone is going to argue that good code without comments is better than the identical code with comments, right? So I hope that we are all in agreement on this at least?!
The simple fact is that it is widely agreed upon, both in industry and in academia, that commenting source code is better than not. Yes, some people are better at it than others... The real issue, however, seems to be whether uncommented code will be accepted for harvesting, yes? Historically the Squeak community has been willing to harvest uncommented code if the harvesters decide that it is worthy for inclusion in the image.
Personally, as someone who is trying to come up to speed in Squeak, it would be a big help if all the classes had at least a short comment as to their intended function so I didn't have to scrutinize and interrogate the source code itself. However, putting my own selfish interests aside, perhaps this would be a more fruitful discussion if those people passionate about the issue of commenting would provide some constructive suggestions on how this problem can be addressed.
Some options: 1) Modify the harvesting process. I have the impression that this is not widely supported due to the perception that it would create additional overhead and, hence, increase the time necessary to get code into the image. Nevertheless, requiring that original authors provide at least minimal comments when they submit new code is the most efficient way of reaching the goal of having useful comments throughout the codebase. Having put forth the effort to write the code in the first place, it is likely that a polite email along the lines of "Thanks for your submission, we would like to include it in the Squeak image provided that you furnish a few lines of comments." would be well received. An alternative is that the harvesters themselves add the comments, but I prefer the former approach. 2) Initiate a new effort (SqueakDoc?) to directly address uncommented code in the squeak image. This is by far the more laborious of the options, but likely necessary either way since the above would only address the new code submissions. If this is the only approach taken, it would truely be unfortunate if it led to the perception that people didn't have to provide comments since the SqueakDoc effort will do it for them.
I would like to see both of the above, but the first option is something that only the harvesters can really enforce. The second option is clearly necessary either way and is something that the wider community can decide to participate in if they care enough. Perhaps the community should simply vote on how they want the harvesting process to be run? This approach has worked very well within the Apache community and I would encourage people unfamilliar with the Apache process to spend a bit of time learning about it - there are some important lessons tobe learned in how to successfully foment a productive and valuable open source community. (This isn't to say that the Squeak community isn't both valuable and productive, but only to say that things could be improved...)
As a last point, I would like to note that having a well documented codebase will ultimately reduce the learning curve associated with contributing to the overall community - a learning curve which may very well prevent some people from contributing simply because they can't find their way around well enough to see what is going on. Keeping the bar to contributing unnecessarily high is a certain recipe for isolating the Squeak community from a potentially much broader user base.
Regards, Elias
The simple fact is that it is widely agreed upon, both in industry and in academia, that commenting source code is better than not.
Would this be the same industry and academia that standardized on C?<s>
Personally, as someone who is trying to come up to speed in Squeak, it would be a big help if all the classes had at least a short comment as to their intended function so I didn't have to scrutinize and interrogate the source code itself.
I concur.
squeak-dev@lists.squeakfoundation.org
-
Blake -
Craig Latta -
David T. Lewis -
Doug Way -
Elias Sinderson -
goran.krampe＠bluefish.se -
lex＠cc.gatech.edu -
Michael Latta -
Peter van Rooijen