I agree with this. Removing formatting from code is really a "lossy compression" and it looses lots of valuable information. And it's not just that poorly formatted code is often a sign of inexperience or bugs - it's also that (at least for me) the style and consistency of a method says a lot about who has written it, how many people have been working on it and similar things. In short, the way in which a method is formatted reveils a lot of subtle information about the writer, its intent and its general working style. I am not certain we want to loose that information.

Cheers, - Andreas

----- Original Message ----- From: "Chris Becker" chbecker@neo.rr.com To: "'The general-purpose Squeak developers list'" squeak-dev@lists.squeakfoundation.org Sent: Saturday, February 28, 2004 6:12 PM Subject: RE: Squeak coding style...

I think there is a great benefit to leaving code formatted exactly how the author wrote it:

Poorly formatted code helps me quickly identify parts of a system that need to be rewritten. You'll typically find more bugs in code that looks like crap. It's like a giant neon sign on the road, "Lousy design ahead!"

So, after 25+ years of hashing and rehashing this issue in every language I've developed in, I now say, "Viva la difference!"

:-D

Chris Becker

-----Original Message----- From: squeak-dev-bounces@lists.squeakfoundation.org [mailto:squeak-dev- bounces@lists.squeakfoundation.org] On Behalf Of goran.krampe@bluefish.se Sent: Saturday, February 28, 2004 7:53 AM To: squeak-dev@lists.squeakfoundation.org Subject: Squeak coding style...

Hi all!

I have been BFAVing quite a bit the latest week and one thing that has annoyed me a bit :) is our lack of consistency in coding style. Sure, it is not a BIG THING - but at the same time a consistent style improves the impression.

Now - we all have different preferences here, but let me show you a hypothetical example:

sillyFy: string "take the argument and sillyfy it" ^ string, ' is silly'.

Ok, there are 6 things here that annoys me. :) Note though that I write this with toungue in cheek! Some of these things are plain silly but I confess - they still bug me. :) Here goes:

1. The comment starts with lower case and has no period. Just looks

sloppy IMHO. This one is actually one that I think we could agree on. Right?

2. There is no empty line between the code and the comment. I like an

empty line there so that I can easily see where the code starts. If there is no comment at all then I usually still have an empty line below the signature before the code. Also hopefully a style convention we could try to follow perhaps.

3. The code should be indented. Agree? :)

4. There is a space after ^. Sure, people do it differently. :)

5. The naming of the parameter "string" is not really in my taste. I

would have liked "aString" better.

6. There is a period after the last statement. Not needed.

Anyway, the above was just to spark the thread. I know this topic is of very low importance though so.... well. :)

regards, Göran

PS. Perhaps we could write a "styleifier"? Some of these things are both easily detected and corrected.

Hi dan

what you describe is a kind of dream. Just before the BC compiler arrived, I started to write another pretty printer but based on the Squeak AST. Then I stopped because I thought that the AST would change. I was never happy with the result. But in the process I learned that - the AST design can also help a lot (lex confirmed that in lucid) having for example a parent link as in RB AST makes a lot of stuff easier, - having a Visitor is a good to achieve variation for the pretty printers (note the s). because this visitor could be used to fileout code also or generate new syntax or HTML. - I was really not happy at all with my result because it was not clever enough to be tweaked. Also writing the tests for the pretty printer was difficult because testing the AST was not good, but testing the resulting pretty printed code was tedious because everytimes I took into account a new construct I may break a lot of tests. Still I wanted to be sure that all the case were well printed.

For the type inferencer, Gilad Bracha was visiting us recently and he made a really improtant point about the idea that you want to have pluggable type system: type system that do not interfere with the language semantics. I will ask him if I can put the slides on the web. One nice consequence is that in fact you would like to be able to annotate any AST elements and also instance variables. So this could be a task for the Compiler Cleaning effort: using the RB AST will already be a step in that direction (this was sad to see that Lex, Anthony and me did the same effort in parallel because we needed

For the type or role, I think that this is extremely important for the instance variables. So normally I used roles for instance variables and type for arguments. But I agree I would really value a type inferencer. May be this is the time to make call for tools :)

Stef

On 28 févr. 04, at 19:32, Dan Ingalls wrote:

...

I agree with this. Removing formatting from code is really a "lossy compression" and it looses lots of valuable information. And it's not just that poorly formatted code is often a sign of inexperience or bugs - it's also that (at least for me) the style and consistency of a method says a lot about who has written it, how many people have been working on it and similar things. In short, the way in which a method is formatted reveils a lot of subtle information about the writer, its intent and its general working style. I am not certain we want to loose that information.

I agree with Andreas about this, but I think it is more a statement about loss in our current formatter than about the impossibility of good automatic formatting. I think we could get *quite close* to something that made us all happy with just a bit more energy put into the formatter.

For instance...

1. Include more white space as real information. I *think* this is

what bothers Andreas about lossiness of the current formatter. For instance, skipping a line between significant sections is one of the most useful gestures in good coding. Also comments embedded in, or to the right of code are different from line-long comments, and ought to be kept as such.

2. Make it easy to personalize the formatter with regard to such

issues as spaces around binary ops and return arrow, empty line before code, block header spading, etc. A set of check boxes and a method in view that changes as you check them.

3. Put some work into the defaults, with input from the community and

suggestions like Kent's.

While I know everyone feels differently about various details, I don't think that a wonderful formatter should be considered an impossibility. I worked pretty hard on the current one years ago, but stopped short of some of the white space subtleties.

It would be nice to have a "benchmark" piece of code that included both challenging structures and tasteful commenting and code. Then we could all judge whether we basically approved or disapproved of a given formatter (and it's personalizing options). Each time someone came up with a new challenge, its archetypal example could be added to the benchmark and the formatter tweaked until we were happy with the result.

• Dan

PS: On the topic of variable names, I happen to oppose the "aString" style of variable naming except when you really can't think of anything better. I feel a variable should be typed by its type, and named by its role (ie "boxCount" instead of "anInteger". Unfortunately we don't have a type inference system and a button to show the types when we want them. Me, I'm going to keep naming by role, and encouraging work on type inference.

Yeap I agree with point c)

d) One of the reasons why I think type inferencers work so poorly is because of the lack of strong enough models in the underlying system. "Just guessing" about messages being sent here and there isn't going to work in my understanding - any type inferencer which is worth its money probably will need some "hints" by framework designers so that users of the framework can have the type inferencer do its work. So some form of "type annotations" will be required to make it work.

Yes this was the point in anymorphic, You could also give some information and based on that the inferencer can work. Gilad mentioned that at the time they did animorphic they used a wrong algorithm for inferencing but now he knows a better one (I forgot). But I keep that in mind.

In fact In VW (so may be in squeak too) the parser accepted name <String> for method definition. We could simply think about the same for instance variables and local... as soon as we are not forced to say it.

stef

On Feb 28, 2004, at 11:57 AM, Chris Becker wrote:

And I like Dan's ideas regarding a configurable formatter. Very cool.

I haven't used Smalltalk/X for a while, but I remember really liking its formatter, which is configurable much as Dan describes. I also like the way it formats as you type, rather than only when you accept the method.

Presumably we can't actually use the code, but it might be a useful source of inspiration.

Cees de Groot wrote:

Hmm... I write code to be read, and often I want to preserve identation just as I wrote it, not because it complies with some code standard but because I've thought long and hard about it and that particular bit of whitespace represents my best shot at making the code readable. I am very much unconvinced that a code formatter will be able to make these decisions, unless it is as intelligent as I am, in which case I'll leave the programming tasks to it as well.

Yes, I agree. The "formatter" I'm referring to is the "prettyPrint" function in the Squeak browser that Dan was talking about. It can be turned on at your discretion.

Personally, I think it'd be a good idea to *recommend* the style as descibed in Best Practice Patterns (because that book seems to mesh reasonably well with accepted practices in the Smalltalk work) and to watch out for 'violations'. But not to be anal about it.

Yes, and the existing pretty printer could be enhanced to display code that conforms more closely to generally accepted standards.

Chris

Hi all!

Dan Ingalls Dan@SqueakLand.org wrote:

PS: On the topic of variable names, I happen to oppose the "aString" style of variable naming except when you really can't think of anything better. I feel a variable should be typed by its type, and named by its role (ie "boxCount" instead of "anInteger". Unfortunately we don't have a type inference system and a button to show the types when we want them. Me, I'm going to keep naming by role, and encouraging work on type inference.

I agree with this. I would only use "aString" if I couldn't come up with something better which is "role based". But I still think the general pattern of "aString" is better than "string".

regards, Göran

...

...

...

"Colin Putney" 03/02/04 15:03 >>>

On Feb 29, 2004, at 1:49 PM, goran.krampe@bluefish.se wrote:

...

Hi all!

Dan Ingalls Dan@SqueakLand.org wrote:

...

PS: On the topic of variable names, I happen to oppose

the "aString"

...

...

style of variable naming except when you really can't think of anything better. I feel a variable should be typed by its

type, and

...

...

named by its role (ie "boxCount" instead of "anInteger". Unfortunately we don't have a type inference system and a

button to

...

...

show the types when we want them. Me, I'm going to keep naming by role, and encouraging work on type inference.

I agree with this. I would only use "aString" if I couldn't come up with something better which is "role based". But I still think

the general

...

pattern of "aString" is better than "string".

I think Stéphane made an important point that's been overlooked. I hadn't thought about it before, but I now notice that I too differentiate between arguments to a message and temps and ivars. With temps and ivars, I always use a role based name. But for arguments, the role is given by the keyword in the selector, so I use a type-indicating name. This is especially useful for accessor methods, because the ivar will have a role-based name, and so one *must* choose a different name for the argument. Describing the same role differently is redundant, but describing the type provides more information. For example, I find this:

name: aString name := aString

preferable to this:

name: theName name := theName

I've not got my copy of Kent's "Smalltalk Best Practice Patterns" to hand, but I seem to recall quite strongly that Kent suggests exactly this: that a parameter name should suggest acceptable types and a temp/ivar name should suggest its role.

Hah, based on Google, the patterns have the following (oh, so obtuse!) names: * Role Suggesting Instance Variable Name; * Role Suggesting Temporary Variable Name; * Type Suggesting Parameter Name.

This doesn't apply to the Crochety Oldbies, but certainly for anyone new to Smalltalk (like me) I cannot recommend this book enough. Actually, I cannot recommend this book enough for _any_ OO programmer - I use lots of these patterns at work writing in Delphi.

And, of course, Kent gives us pretty sane code style guidelines as well.

frank

On Saturday 28 February 2004 10:49 am, Julian Fitzell wrote:

I only agree with about half of them, but I'm not getting involved in *this* holy war... ;)

That's true. Anyone want to talk about licenses?

Sorry, sorry, sorry. I made my previous e-mail a bit too concise.

My comment was a short version of this, not so short version:

"The most important code styling issue is that the code writer keeps the code reader in mind when writing code. We do not write code for a computer, a computer accepts almost anything and understands almost nothing. We write code for a human and we want to minimize the effort needed by that human to understand what we mean.

This means that the code and the code style has to be adapted to the reader, the reader's prior knowledge and any common conventions in the reader's community. It is a question of an intelligent mind communicating with another intelligent mind.

The Scientific American's advice to authors: Never overestimate the prior knowledge of your reader. Never underestimate the intelligence of your reader.

This also means that I do not believe in automatic pretty-printers. They can never hide the unimportant, highlight the important and communicate what the reader needs to know. Further, as said by others, it hides the writer's unconscious "body language" that is reflected in the code and gives the reader important hints as to the mind-set of the writer. Artificial intelligence is always artificial, never intelligent.

Most Squeak programmers including you, Stef, write code for our community to read and to use. My initial ironic e-mail was addressed to the few that have not yet matured to the point where they realize the importance of style - any style.

Regards --Trygve

At 28.02.2004 15:53, you wrote:

Trygve wrote:

...

A question to anybody writing code in any language: Do you intend the code to be read, or is it write-only? A word of comfort: If you don't reveal your name: Don't worry, we understand.

I, for one, intend for my code to be read. And modified. [ And read. And modified. ] repeatForever.

In fact, when I write code, I spend a significant amount of time ensuring that my code is as correct, clear, concise, and consistent as possible so that the next person who reviews it (usually me) can understand the intent and function (including me).

At issue here, though, is whether we can "legislate" style. You can't treat code like sausage, extruding it through a meat grinder when a method is accepted so it all comes out uniformly (cat gut not included). ;-)

But we *can* enhance the existing pretty-printer which can be turned on by someone during code review to make sausage more digestible.

(OK, I'd better quit with the meat metaphor while I'm ahead!!)

Chris

goran.krampe@bluefish.se wrote:

Hi all!

This thread slided away from what I was trying to talk about. Sure, interesting as always but...

Personally I think pretty printing is useful - but I never use it. I tend to agree with Andreas that the code *as written* includes hints and information that I don't want to loose, like whitespace and various formattings of nested blocks.

(Sorry to slide the topic back to pretty printing here... :) )

I think I agree roughly with Dan's position... the current pretty printer loses formatting information on a couple of important things, blank lines (for separating sections of code) and comment locations (whether at the beginning of a line or trailing an existing line of code). But other than that, I think it's perfectly legitimate to lose all other formatting information. If we had a *good* pretty printer which kept the blank lines and comment locations and was reasonably customizable, I'd probably use it all the time.

Another thing is that I think pretty printing is *hard*: For example code with blocks tend to be hard to format according to rules so that it always "looks good". I have given up on trying to figure out what my own personal rules are - I seem to always adapt my style to the code at hand.

Agreed that it's not easy.

...

I just want us to think if we can agree on *a few simple rules*.

For example - is it really too much to ask that comments which are meant to be full sentences are formatted accordingly to proper english? (first word with capital letter, ending with a period)

Or is it really too much to ask that all classes have a class comment? Even if it is only one or two lines? Missing class comments is IMHO totally unacceptable *in the standard packages*.

So please people, could we get back to this issue? Do you agree with me that a few simple rules could actually be a good thing to have regarding the code in the "standard" Squeak packages?

I would agree with the couple of simple rules you just mentioned.

This reminds me that I am still planning on finishing a "changeset validator" tool which could make some simple automated checks before a changeset could be incorporated as an update. The validator could run whenever someone uses "send to list" from the changesorter or BFAV, and also when approving an item, etc. This could enforce a few basic things, such as the rule that all new classes must include class comments. (This would make my job as update stream maintainer easier too, as it would prevent things like missing method timestamps, etc.)

I should actually have some time to work on this after 3.7 goes beta...

- Doug

Hi Andreas and all!

"Andreas Raab" andreas.raab@gmx.de wrote:

...

Another thing is that I think pretty printing is *hard*: For example code with blocks tend to be hard to format according to rules so that it always "looks good". I have given up on trying to figure out what my own personal rules are - I seem to always adapt my style to the code at hand.

Interesting point, since I do the same - for example, if I'm in a method using underscore as assignment I use underscore, if I see colon-equals I use colon-equals. Etc.

Right. But also - when I write code with a few nested blocks - I always end up formatting it differently. I just can't seem to settle on ONE way to indent/format code with nested blocks.

...

I just want us to think if we can agree on *a few simple rules*.

Agreeing???? On Squeak-dev????? About style???? ;-)

:) Yeah, I know. Pretty outlandish!

...

For example - is it really too much to ask that comments which are meant to be full sentences are formatted accordingly to proper english? (first word with capital letter, ending with a period)

Or is it really too much to ask that all classes have a class comment? Even if it is only one or two lines? Missing class comments is IMHO totally unacceptable *in the standard packages*.

So please people, could we get back to this issue? Do you agree with me that a few simple rules could actually be a good thing to have regarding the code in the "standard" Squeak packages?

I think it is possible to agree on a (very) limited set of rules but whether those are actually enforcable is a different matter. I'm no believer in rejecting stuff based purely on a formal basis as most of the people are in for the fun of it and if people are it's hard to force them to adapt any particular style. It is much more helpful to educate people gently along the right lines.

True. But on the other hand - if the rules are few, obvious and pretty much 100% agreed upon - like for example starting sentences in proper english - then we might even be able to automate it so that code entering these standards packages (I am of course talking *only* about those) is automatically transformed to be compliant.

The lack of class comments can not be automated away of course, but I agree with you that the new Red Sign should make it better in the long run. Also - I will scream out LOUD if I ever see a harvester approve classes into standard packages that lack class comments. Really. It would piss me off. Seriously. We do need to make things *better*, not worse.

For example, I believe that the embarrassment of having a big red "THIS CLASS HAS NO COMMENT" sprayed right over your face will have quite an impact on the quality of class comments long-term. This is a wonderful addition both in terms of usability as well as in terms of educating people *why* they should write class comments.

Yep. And btw... SM creates all new wonderful opportunities to harass people. We now have a clear mapping from developer initial all the way to the SM account. Hehe... (horns growing out of forehead) Hmmmm.... :)

Cheers,

• Andreas

regards, Göran

Andreas Raab wrote:

For example, I believe that the embarrassment of having a big red "THIS CLASS HAS NO COMMENT" sprayed right over your face will have quite an impact on the quality of class comments long-term. This is a wonderful addition both in terms of usability as well as in terms of educating people *why* they should write class comments.

Perhaps this should be expanded so that uncommented methods (perhaps testing for more than a smallish number of bytecodes?) also have such a comment automagically added? Since we have the writers initials (normally) we could even make it be something like

"That idiot tpr has not bothered to comment this method. What a loser"

tim

tim Rowledge wrote:

...

Perhaps this should be expanded so that uncommented methods (perhaps testing for more than a smallish number of bytecodes?) also have such a comment automagically added? Since we have the writers initials (normally) we could even make it be something like

"That idiot tpr has not bothered to comment this method. What a loser"

tim

or how about

"The author, jgp, has no idea what this method does. Use with extreme caution."

John M McIntosh wrote:

Well not that anyone has noticed that tpr who merges the VM code manages of course to zap the original author's initials JMM to tpr so that history is lost... Mind that means he supports those changes eh? Perhaps having the tool preserve existing initials would be helpful.

Very true. I'd hate to be blamed for other people's mistakes. I make quite enough of my own to be going on with...

tim

Perhaps this should be expanded so that uncommented methods (perhaps testing for more than a smallish number of bytecodes?) also have such a comment automagically added? Since we have the writers initials (normally) we could even make it be something like

Interesting idea, but IMHO no. I don't even quite agree that every class needs a comment; if you see this class hierarchy:

LambdaExpression LEVariable LEApplication LEAbstraction Then it is utterly pointless to go through putting comments like "a LEVariable is a lambda expression variable" and "a LEApplication is a lambda expression application". If you know what a lambda expression then you don't want a comment in the subclasses. The name suffices. Or how about this one:

LargeInteger LargePositiveInteger LargeNegativeInteger Sure, put a comment in LargeInteger to say what "large" means. But a comment would be useless in the two subclasses.

With methods it's even more frequently the case that a comment is a wasted distraction and an unnecessary maintenance burden. We really don't need a lot of this kind of comment:

sillify: aString "sillify the argument"

-Lex

tim Rowledge tim@sumeru.stanford.edu wrote:

...

LargeInteger LargePositiveInteger LargeNegativeInteger Sure, put a comment in LargeInteger to say what "large" means. But a comment would be useless in the two subclasses.

I disagree, obviously given my above comments. LPI should becommented to explain that it represents only positive values, that the code may need to create LNIs as a result of subtractions, that normalisation may produce SmallIntegers(we recently had list messages relating to some confusion about this). LNI would benefit from explanations of a similar nature but obviously LPIs are created asa result of -ve * -ve and all that.

These are important things to document, but almost all of them should be in the superclass LargeInteger. The only new information that is in LPI or LNI is "positive" or "negative", plus possibly "see the superclass". It is not a bad thing if such simple comments are left out entirely.

Here's a better example: class HtmlEntity, which has a subclass for each HTML tag. Does HtmlImage really need to have a comment like "HtmlImage is for <image> entities" ? That seems wasteful to me. To understand HtmlImage you need to understand its superclass; once you understand its superclass, no comment is necessary. HtmlImage is no more and no less than what it's name suggests: an entity for images.

I don't think this kind of class is at all common, but it does come up occasionally. Some classes do not need comments.

With methods, I expect the reverse: the majority of methods should *not* have a comment. I find that with a good class comment and with good general documentation of what is going on, that the meaning of most individual methods are quite obvious. For example, once you understand what, generally, a Morph is about, then you don't need to explain what #width is. The name says it all and an extra comment will not help.

For amusement, I just looked at the 13 implementors-of #width. 10 have no comment, of which at least 9 do not need a comment (I can't evaluate the 10th without learning more about the class first). 1 implementor, in DisplayObject, has a good, helpful comment. 1 implementor simply says "for compatibility". And to round it out, Rectangle's implementator has a classic wasted comment: "Answer the width of the receiver". IMHO this is all ideal except for Rectangle's method comment, which should be removed.

-Lex

I might add that comments in either the class or the method (and I do think that non-trivial methods DO need comments and/or refactoring) are there to help two classes of users: those new to smalltalk and/or Squeak, and users unfamiliar with the class.

tim Rowledge wrote::

Lex Spoon wrote:

...

Here's a better example: class HtmlEntity, which has a subclass for each HTML tag. Does HtmlImage really need to have a comment like "HtmlImage is for <image> entities" ? That seems wasteful to me. To understand HtmlImage you need to understand its superclass; once you understand its superclass, no comment is necessary. HtmlImage is no more and no less than what it's name suggests: an entity for images.

I'm going to disagree again here; this is ripe with possibility. One might include a pointer to the appropriate page on the W3C site where html image tags are defined, have a list of any limitations or problems with their use within the context of the system etc.

But let's not throw too much of our time at specifics. Clearly people can differ on what they think is appropriate. The good news is that more than is needed by one person is unlikely to be troublesome to that person, barring otiose prolixity and redundantly excessive verbiage, and it is probably helpful to others. The bad news is that carefully written highly explanatory commetns can be ruined by code being changed without the comment being updated.

tim

Hi All,

With methods, I expect the reverse: the majority of methods should *not* have a comment. I find that with a good class comment and with good general documentation of what is going on, that the meaning of most individual methods are quite obvious.

Please, can we distinguish between method and message comments? For example in the method:

! MyClass methodsFor: 'aditions'! add: anObject "Add anObject to the receiver."

^myContents addLast: anObject ! !

The "Comment" here is the comment of the MESSAGE. Not the comment of the method.

Message comments MUST be the same in all environment and must be mantained as a part of the message. A message has a name(aSelector), argument names, and a Comment.

All classes that implements the message #add: must use anObject as the argument and the SAME comment.

Why the same selector? (it is clear why) Why the same argument names? - Because if there is any restriction in the arguments semantics, it must be treated as another message (no polimorphism). Why the same comment? - because the comment of the message MUST define the semantics of the MESSAGE and no any local detail of implementation.

What about method(code) comments? I this that code comments are not necesary for the smalltalker, because the methods must not be long enough to be explained.

I think that class comments are very powerfull for documenting, but ony refer to object level descriptions. It can be very interesting to have any posibility to document frameworks e.g. comments for class categories. The use of morphs for documenting can be very interesting Embedding multimedia comments in chunk format can result in loosing readability of sources... how can we solve this?

What do you think about attaching comments to softare elements? and mantain them by a comment tool?

cheers, Ale.

----- Original Message ----- From: "Lex Spoon" lex@cc.gatech.edu To: "The general-purpose Squeak developers list" <squeak-dev@lists.squeakfou ndation.org> Sent: Wednesday, March 03, 2004 3:04 AM Subject: Re: Back to the issue... (was RE: Squeak coding style...)

tim Rowledge tim@sumeru.stanford.edu wrote:

...

...

LargeInteger LargePositiveInteger LargeNegativeInteger

Sure, put a comment in LargeInteger to say what "large" means. But a comment would be useless in the two subclasses.

I disagree, obviously given my above comments. LPI should becommented to explain that it represents only positive values, that the code may need to create LNIs as a result of subtractions, that normalisation may produce SmallIntegers(we recently had list messages relating to some confusion about this). LNI would benefit from explanations of a similar nature but obviously LPIs are created asa result of -ve * -ve and all that.

These are important things to document, but almost all of them should be in the superclass LargeInteger. The only new information that is in LPI or LNI is "positive" or "negative", plus possibly "see the superclass". It is not a bad thing if such simple comments are left out entirely.

Here's a better example: class HtmlEntity, which has a subclass for each HTML tag. Does HtmlImage really need to have a comment like "HtmlImage is for <image> entities" ? That seems wasteful to me. To understand HtmlImage you need to understand its superclass; once you understand its superclass, no comment is necessary. HtmlImage is no more and no less than what it's name suggests: an entity for images.

I don't think this kind of class is at all common, but it does come up occasionally. Some classes do not need comments.

With methods, I expect the reverse: the majority of methods should *not* have a comment. I find that with a good class comment and with good general documentation of what is going on, that the meaning of most individual methods are quite obvious. For example, once you understand what, generally, a Morph is about, then you don't need to explain what #width is. The name says it all and an extra comment will not help.

For amusement, I just looked at the 13 implementors-of #width. 10 have no comment, of which at least 9 do not need a comment (I can't evaluate the 10th without learning more about the class first). 1 implementor, in DisplayObject, has a good, helpful comment. 1 implementor simply says "for compatibility". And to round it out, Rectangle's implementator has a classic wasted comment: "Answer the width of the receiver". IMHO this is all ideal except for Rectangle's method comment, which should be removed.

-Lex

"Alejandro F. Reimondo" aleReimondo@smalltalking.net wrote:

What do you think about attaching comments to softare elements? and mantain them by a comment tool?

I love it. The main thing is to make it accessible in the UI.

As a start, if you select a message category (third pane) in a browser, one option in the right hand column could be <comment>. Selecting this lets you edit a comment for that category.

Similarly, it would be great if at least instance variables and global variables could have comments. Mousing over them would give you a comment for them. Clicking the "?" button in a browser could give you a multi-pane comment editor, where you have a pane per variable instead of just one big pane. For global variables, wells, we should really have a global variables browser shouldn't we? Right now there is *no* UI in Squeak for manipulating the existence of global variables.

I will leave off commentary on messages vs. methods because other followups have covered it. Let me just say it as well is an excellent idea to put into the tools.

One final issue to consider during all of this: it must *not* become a large extra burden for programmers to maintain this commentary. It should be very well integrated into the tools, and it should be optional during initial development.

This is a terrific direction for a Smalltalk-like environment and I hope people run with it!

-Lex

Doug Way dway@mailcan.com wrote:

On Wednesday, March 3, 2004, at 09:35 PM, Lex Spoon wrote:

...

...

Perhaps this should be expanded so that uncommented methods (perhaps testing for more than a smallish number of bytecodes?) also have such a comment automagically added? Since we have the writers initials (normally) we could even make it be something like

Interesting idea, but IMHO no. I don't even quite agree that every class needs a comment; ...

I agree about not adding method comments automagically, but disagree about class comments.

Thank you, thank you. I was thinking me and Tim were somehow abbe-normals here for a second. Phew. ;)

Sort of making up a figure here, but I'd say 98% of all classes in the base release need to have class comments. Given that, I think it would be reasonable to enforce that all new base release classes have to have class comments, even if it means that the 2% of classes which don't really need them have to have them too.

Yes - and again - I of course repeat my "How do I know if it is intentionally left blank or simply blank because the original authors were sloppy?"-argument.

On the other hand, I'd say maybe, um, only 50% of so of methods really need to have toplevel comments, so I agree that we don't want to enforce the addition of such a large proportion of unneeded comments.

Just to make sure - I never suggested that. I merely suggested that perhaps we should use proper english sentences and perhaps standardize on a blank line after a method comment + indentation of method code one tab. But obviously having a few rules is tabu in this community, sigh.

Sometimes I really do understand why some people think Squeak is a mess, especially if we can't even acknowledge the fact that we need to shapen things up a bit.

• Doug

regards, Göran

Hi all!

Julian Fitzell julian@beta4.com wrote:

goran.krampe@bluefish.se wrote:

...

Sometimes I really do understand why some people think Squeak is a mess, especially if we can't even acknowledge the fact that we need to shapen things up a bit.

I don't think it's anything like that. Some people want rules - they just want *their* rules. I happen to think general coding standards are a good thing, I just happen to disagree with half of your suggestions.

The important point with my posting was the embedded question: Can we and should we try to come up with a few rules for the standard packages?

My little examples were NOT the point at all. Forget about them! I just whipped them up to show what I am talking about.

And I don't want to get involved in the discussion because I know that *other people* will disagree with a different half.

Most of those who don't want rules probably just realize the improbability of coming to any agreement.

Ok, so in short you think it is pointless to even *try*? And how would we ever be able to evolve Squeak with say Traits if we can't even agree on some simple, small coding conventions *in the standard packages*?

Again - please people, come on! Can't at least some of you say "Hey, you got a point here. Perhaps we could try to introduce a few standard conventions in our *standard packages*."?! And then we can take the discussion from there.

If not - then it truly disappoints me, I really thought this community was... capable of constructive cooperation instead of petty "No, I don't like this or that!" or "Forget it, no point..."

regards, Göran

Colin Putney wrote:

Actually, I don't think it's petty at all. Given that:

1. Style is a very subjective thing, and it will be difficult to get a

community consensus.

2. Pretty printers can help by ensuring that those who are really

annoyed by bad style don't have to look at it. (Ok, the currently available pretty-printer isn't ideal, but still.)

3. Even when badly styled, Smalltalk is one of the most readable

programming languages available.

I think it's reasonable to conclude that the initial effort required to reach a consensus and the on-going effort required to enforce it wouldn't be worth the benefits it would bring. I'd characterize this position as "Our energies are better spent elsewhere," rather than "Forget it, no point..."

Clearly you disagree, and that's great. But part of constructive cooperation is deciding on priorities, and style conventions don't seem to be high on many people's lists.

Colin

Thought I'd throw in my two cents (and also see if I can post from this email address now) :-)

Yes, style is subjective. And, I don't give a hoot what the style being used is, just as long as there is a consistent style for the code I need to look at.

I *love* the pretty-printer. And I don't really care *if* it gets changed, or *how* it gets changed (I can adapt to whatever it is). I just want it to continue to be there, in one form or another.

Nevin

Goran, Hey, you got a point here. Perhaps we could try to introduce a few standard conventions in our *standard packages*."?! And then we can take the discussion from there!

We need to get innovations out quickly, even if they are dirty. (I really need the stuff I'm using right now. It would have been nice if it had been more complete. But this is much better than not having it at all.

But a package shouldn't be upgraded to a *standard package* before it fulfills a few quality requirements - and that includes a minimum of comments and/or documentation.

We want to experiment freely. And we want a standard release that newcomers can use without going mad.

I was ashamed when I heard that while it takes 12 months to become proficient in C++, it takes a year for Smalltalk. (Claimed in the halls at an OOPSLA many years ago)

--Trygve (I'm not yet fully into the Squeak community and may be talking out of turn)

At 03.03.2004 20:22, you wrote:

Colin Putney cputney@wiresong.ca wrote:

...

On Mar 3, 2004, at 1:25 PM, goran.krampe@bluefish.se wrote:

...

Ok, so in short you think it is pointless to even *try*? And how would we ever be able to evolve Squeak with say Traits if we can't even agree on some simple, small coding conventions *in the standard packages*?

Again - please people, come on! Can't at least some of you say "Hey, you got a point here. Perhaps we could try to introduce a few standard conventions in our *standard packages*."?! And then we can take the discussion from there.

If not - then it truly disappoints me, I really thought this community was... capable of constructive cooperation instead of petty "No, I don't like this or that!" or "Forget it, no point..."

Actually, I don't think it's petty at all. Given that:

1. Style is a very subjective thing, and it will be difficult to get a

community consensus.

Of course. But... sigh.

• I am only talking about simple small things automatically enforceable.
• And I am only talking about the standard packages.

Either I am not making sense or noone is listening, whichever it ends with this posting.

...

2. Pretty printers can help by ensuring that those who are really

annoyed by bad style don't have to look at it. (Ok, the currently available pretty-printer isn't ideal, but still.)

Not the best pretty printer in the world will fix for example:

• Class comments
• Proper english sentences

...

3. Even when badly styled, Smalltalk is one of the most readable

programming languages available.

I think it's reasonable to conclude that the initial effort required to reach a consensus and the on-going effort required to enforce it wouldn't be worth the benefits it would bring. I'd characterize this position as "Our energies are better spent elsewhere," rather than "Forget it, no point..."

Clearly you disagree, and that's great. But part of constructive cooperation is deciding on priorities, and style conventions don't seem to be high on many people's lists.

Well then, as I said. It ends right there. The lack of support in this is quite telling. Thanks for listening.

...

Colin

regards, Göran

On Wed, 3 Mar 2004, Colin Putney wrote:

3. Even when badly styled, Smalltalk is one of the most readable

programming languages available.

Alas, I don't find that to be the case at all.

I've been playing with Squeak since October. I've read Kent Beck's Practice Patterns book front to back. I've been through Mark Guzdial's entire white book, with Squeak up and typing in examples and trying them as I go. I did the Morphic chapter in Mark+Kim's blue book, again typing in examples and trying them as I went. I've played around with writing my own smalltalk student, and have been helping an undergrad working with me debug my code.

But even after all that... stick a complicated line of Smalltalk in front of me, and I freeze in bewilderment for at least a few seconds, and then if I very carefully step through each token at a time, and write in parentheses (if I'm reading a book) or type in parentheses (if I'm actually at a Squeak browser) according to the precedence rules: unary first, binary second, message third. I find reading Smalltalk to be slow and painful. I feel like the language turns me into a human parser, and I feel the Ls and Rs and numbers percolate in my brain.

Repeat same painful process for next line.

It can take me quite a while to read through and understand a method.

I don't think it's just the unusual syntax - Lisp/Scheme has an unconventional syntax, but I picked that up almost instantaneously and usually have not trouble reading a Lisp program.

I like Smalltalk, and I adore Squeak. I see it as the right way to do things. Although I have a hard time reading Smalltalk, the consistency of the language strongly appeals to me. The block closures that let you roll your own control structures are brilliant. I want to embrace Smalltalk. Morphic is the coolest thing about Squeak, and I never want to go back to doing things the non-Morphic way.

But the claim "It is no longer necessary to write cryptic programs" on the www.smalltalk.org site is utter BS. Smalltalk is often extremely cryptic.

Anyway, I just want to throw in the thought that for many on this list, Smalltalk may flow smoothly, but for the world out there seeing it for the first time, it may not be so obvious, and there may be many potential new Smalltalkers who will get turned off and not dig deeper due to their initial frustration.

Indeed, it was only the fact that someone I know and respect a lot (Mark Guzdial) was a big Squeak fan that gave me the fortitute to keep at it.

- Aaron

-----------------------------------------------------------------------------

Dr. Aaron Lanterman, Asst. Prof. Voice: 404-385-2548 School of Electrical and Comp. Eng. Fax: 404-894-8363 Georgia Institute of Technology E-mail: lanterma@ece.gatech.edu Mail Code 0250 Web: users.ece.gatech.edu/~lanterma Atlanta, GA 30332 Office: GCATT 334B

On Mar 3, 2004, at 12:41 PM, Colin Putney wrote:

PS. Hey Avi, what was that you said waaaaay back when we were starting Iphiginia? Something like, "among the enlightened there are Lispers and Smalltalkers... I know which one I am." Was that quoted from somebody else, or off-the-cuff?

Off the cuff. Too bad conversations in cafés don't get archived so we'll never know exactly what it was...

Avi

On Mar 3, 2004, at 12:23 PM, Aaron Lanterman wrote:

But even after all that... stick a complicated line of Smalltalk in front of me, and I freeze in bewilderment for at least a few seconds, and then if I very carefully step through each token at a time, and write in parentheses (if I'm reading a book) or type in parentheses (if I'm actually at a Squeak browser) according to the precedence rules: unary first, binary second, message third. I find reading Smalltalk to be slow and painful. I feel like the language turns me into a human parser, and I feel the Ls and Rs and numbers percolate in my brain.

Just be glad you're not using Self...

foo at: 1 Put: bar at: 3

is

foo at: 1 Put: (bar at: 3).

Why? Capitalization...

To tie this in with the pretty printing discussion - has anyone done any work on graphical cues for precedence that are less intrusive than parens? I'm thinking of things like subtly adjusting the spacing so that unary selectors are slightly closer to their receivers, etc.

Avi

On Mar 3, 2004, at 2:14 PM, Aaron Lanterman wrote:

On Wed, 3 Mar 2004, Avi Bryant wrote:

...

parens? I'm thinking of things like subtly adjusting the spacing so that unary selectors are slightly closer to their receivers, etc.

Hmmm... in the parsing, the unary messages tend not to give me trouble. I just pretend I'm writing in Forth.

Why pretend?

http://map1.squeakfoundation.org/sm/package/9b0b34f7-15ae-4b73-839d -9262988ff276

On Wednesday 03 March 2004 17:23, Aaron Lanterman wrote:

But the claim "It is no longer necessary to write cryptic programs" on the www.smalltalk.org site is utter BS. Smalltalk is often extremely cryptic.

As you say in the subject, this varies from person to person. My experience is that most of the population would prefer to read Smalltalk to C, Cobol to Fortran, Pascal to Lisp and so on. Think of the success that Hypercard once was. I will fully agree, however, that the current generation of programmers might find Smalltalk less readable than Java or something.

It depends in part on your previous experience and in part on learning style and work habits. In the 1980s the big issue was

NOT ( done OR ( count>7 AND remaing=0 )) vs !( done || ( count>7 && remaining==0 ))

If you tend to read the program "aloud" in your head, then the first version might be easier to understand. If you tend to parse things visually, on the other hand, then the second version might make sense faster.

In the Squeak system browser, try choosing "tiles" from the rightmost button and see if that makes things better or worse for you. How about colorPrint?

I am very interested in this subject since I defined a new syntax for Neo Smalltalk (http://www.merlintec.com:8080/software/4) where I aim for simplicity by making the user do most of the parsing work when entering the source.

-- Jecel

On Thu, 2004-03-04 at 10:37, Aaron Lanterman wrote:

On Wed, 3 Mar 2004, Jecel Assumpcao Jr wrote:

...

In the Squeak system browser, try choosing "tiles" from the rightmost button and see if that makes things better or worse for you. How about colorPrint?

Hmmmm, I can't seem to find what you're referring too... when I pull up a Browser and right click (ctrl-click on my PC laptop), I get "go behind," "add menu," "duplicate," "embed into..." Am I looking in the wrong place? I'm running 3.6.

In the standard browser you should see a row of buttons below the top set of panes and possibly below the annotation pane if you have that enabled (highly recommended). The buttons are labelled 'browse', 'senders', 'implementors', etc. with the last one being a little different with non-round corners. This is the button to which Jecel is referring. If you don't see this row of buttons then open up the preferences (accessible from the world menu appearance -> preferences) and click 'browsing' in the 'tabs' at the top. Note an open labelled 'optionalButtons' and be sure that is selected. While you are there go ahead and ensure that 'annotationPanes' is also enabled. Open up a new browser instance and you should now have the annotation and buttons panes.

Ken

• Aaron

---

Dr. Aaron Lanterman, Asst. Prof. Voice: 404-385-2548 School of Electrical and Comp. Eng. Fax: 404-894-8363 Georgia Institute of Technology E-mail: lanterma@ece.gatech.edu Mail Code 0250 Web: users.ece.gatech.edu/~lanterma Atlanta, GA 30332 Office: GCATT 334B

On Wed, 3 Mar 2004, Aaron Lanterman wrote:

in examples and trying them as I went. I've played around with writing my own smalltalk student, and have been helping an undergrad working with me

Ooops. I meant to say "played around with writing my own smalltalk code." My skills are not yet at the level of being to create a simulation of an undergraduate student in squeak. :)

- Aaron

-----------------------------------------------------------------------------

Dr. Aaron Lanterman, Asst. Prof. Voice: 404-385-2548 School of Electrical and Comp. Eng. Fax: 404-894-8363 Georgia Institute of Technology E-mail: lanterma@ece.gatech.edu Mail Code 0250 Web: users.ece.gatech.edu/~lanterma Atlanta, GA 30332 Office: GCATT 334B

Hi there,

I'm currently working on writing my first real Smalltalk program, "real" as in a program to solve an actual problem I need solved, and not a toy example just to get used to the language.

Two quick questions:

1) One thing is driving me completely nuts: Sometimes I'll be writing a method, and would like to leave it half finished - maybe making reference to a new instance variable I now realize I need - look around at some other stuff, and then go back to it. But when I do that, it asks if I want to save changes, and it forces me to accept it in order to save the changes, but it will only accept it if it's a real working piece of code. To work around this problem I generally have a lot of browser windows open.

Is there a way to tell Squeak, "look, don't compile this yet, it's not ready to go, but please do save the text, I promise I'll come back to it?"

When I'm editing my MATLAB functions, it's perfectly alright for me to be bouncing back and fourth between five different functions, all stored in different files, each partially finished as I'm writing something.

2) Suppose you meant to make a class method, but you forgot to hit class and wind up entering it as an instance method. Is there an easy way to tell squeak "hey, this is currently an instance method, but that's not right, just move this over to the class side?" (i.e. without cutting and pasting the code and all that)

Thanks!

- Aaron

-----------------------------------------------------------------------------

Dr. Aaron Lanterman, Asst. Prof. Voice: 404-385-2548 School of Electrical and Comp. Eng. Fax: 404-894-8363 Georgia Institute of Technology E-mail: lanterma@ece.gatech.edu Mail Code 0250 Web: users.ece.gatech.edu/~lanterma Atlanta, GA 30332 Office: GCATT 334B

On Mar 12, 2004, at 10:47 PM, Hans-Martin Mosner wrote:

...

That's the right way to do it - leave a browser window open, define the inst var in another window, and come back to the first one.

Though I do like the recently posted enhancements that let you declare that an unbound variable reference should be to a new inst var or even a new class - writing code that way has a nice "just in time" feel.

Wasn't the inst var enhancement supposed to go into 3.7? Doesn't look like it has yet.

Avi

Hi Stef,

I made a fix to Lucas' code, so that the "declare inst var" menu option works correctly. The cs was posted to this list and named DeclareInstVarFix-rr. Lukas' enhancement was included, but commented out as it didn't work in all cases.

By the way, I posted a cs to allow an unknow global variable to be directly defined as a class (DeclareClass-rr).

Since I've been unable to load the BFAV (this seems related to the recent thread about that), I've been unable to check if they are visible on it. I thought that bugs and fixes posted via this list were also forwarded to the squeak-harvest list. Am I correct, or shall I post all my fixes to the squeak-harvest list ?

Romain

stéphane ducasse a écrit:

can you precisely identify it that I add it to the list of cool stuff

On 13 mars 04, at 07:54, Avi Bryant wrote:

...

On Mar 12, 2004, at 10:47 PM, Hans-Martin Mosner wrote:

...

...

That's the right way to do it - leave a browser window open, define the inst var in another window, and come back to the first one.

Though I do like the recently posted enhancements that let you declare that an unbound variable reference should be to a new inst var or even a new class - writing code that way has a nice "just in time" feel.

Wasn't the inst var enhancement supposed to go into 3.7? Doesn't look like it has yet.

Avi

Am 13.03.2004 um 14:51 schrieb rrobbes:

Hi Stef, I made a fix to Lucas' code, so that the "declare inst var" menu option works correctly. The cs was posted to this list and named DeclareInstVarFix-rr. Lukas' enhancement was included, but commented out as it didn't work in all cases. By the way, I posted a cs to allow an unknow global variable to be directly defined as a class (DeclareClass-rr).

Yes, both are in BFAV. I have tested and approved DeclareClass-rr. For DeclareInstVarFix-rr we now need a new version that does not stomp on the class-related changes... will post a fixed version.

Marcus

-- Marcus Denker marcus@ira.uka.de

On Saturday, March 13, 2004, at 04:02 AM, Trygve Reenskaug wrote:

... I tend to have at least two browsers open; One for the class I am developing and another for library lookup.

P.S. I still seem to end up with many windows.

You might want to take a look at the Whisker Browser, which I just posted an updated version of on SqueakMap. It attempts to deal with the problem of having many browsers open, by letting you multi-select methods and classes and view the stacked multiple selections in a single window.

Browsers, hierarchy browsers, protocol browsers, method browsers are all useful for their specialities. I sorely miss the very old Tectronix browser that elegantly combines them all. I believe there is work going on in this direction. If not, I hope to find time writing one.

I agree to a large extent. Whisker integrates the functionality of the hierarchy browser, at least.

The current Protocol Browser in Squeak is useful, but I often think it would be simpler to just have a menu option in the regular Browser (or Whisker etc.) which would let you see the inherited methods there if you wanted, and not have to open a separate window.

-Doug

Colin,

I haven't got the original Tectronix browser, but I have our own derivative. A screen shot is attached.

The lower pane is the normal code pane. The lists from left to right are The normal categories The usual classes within the selected category The third column is split into two: - The bottom list is a multiple selection list of superclasses, class, subclasses - The top list shows the protocols in the classes selected below. Protocols of the selected class are shown bold - The third column shows methods of the selected classes/protocols. Methods of the selected class are shown bold All methods in all selected classes are shown, so it is possible to browse e.g., the 'super release' method. The buttons are 'supers' - automatically select all superclasses except Object 'subs' - automatically select all subclasses 'names' - show class name with method name

This browser effectively replaces the normal browser, the protocol browser and the hierarchy browser, and does so in a single window.

I can't remember the Tektronix browser, but believe this one looks very similar. There are differences in functionality, though.

I can't see a point in porting the OOram browser to Squeak. There are so many good ideas in the Squeak image and in the community that it seems better to use it as one of the inputs to the requirement specification for a really useful browser. It seems that good work is already under way - I am looking forward to use the results.

Best regards --Trygve

At 15.03.2004 10:34, you wrote:

On Mar 13, 2004, at 4:02 AM, Trygve Reenskaug wrote:

...

P.S. I still seem to end up with many windows. Browsers, hierarchy browsers, protocol browsers, method browsers are all useful for their specialities. I sorely miss the very old Tectronix browser that elegantly combines them all. I believe there is work going on in this direction. If not, I hope to find time writing one.

Reducing window clutter is one of the purposes of the "chasing" browsers that are part of OmniBrowser. (Available on SqueakMap, bleeding edge version here: http://monticello.wiresong.ca/ob/.) I'd be very interested to know what you think of them.

Also, being a relatively new Smalltalker, I'm not familiar with the Tectronix browsers. Can you describe more specifically how they worked (interface-wise) and what you liked about them? Any grizzled ST veterans got Tectronix documentation lying around?

Colin

Hi Jon,

Is the code lying down somewhere (and adequatly licensed), so that someone could do the porting effort ?

Thanks, Romain

Back when I worked at The Object People, Anthony Lander and I wrote a browser in Visual Smalltalk that solved this problem quite nicely. You could, at any point in time, push the entire state of the browser on a stack, including the dirty state of the text pane. You could go off and explore other parts of the system, add inst vars, etc, and then one keystroke would pop you back to exact state you were in before.

It was very nice to use, allowing for quite context changes without littering the desktop with extra windows.

Unfortunately, we never did get this browser ported to Squeak -- the state push/pop was just one of the cool things it had.

Thanks Jon,

I'll try to have a look a it someday. It seems rather big though, so I don't know yet how to tackle the problem. What other interesting features did this browser have ?

Romain

Jon Hylands a écrit:

On Sat, 13 Mar 2004 14:54:20 +0100, "rrobbes" rrobbes@info.unicaen.fr wrote:

...

Is the code lying down somewhere (and adequatly licensed), so that someone could do the porting effort ?

Well, I have the code, and since The Object People doesn't exist anymore, and this was never an official product that they were selling or offering to clients, and its written for a Smalltalk that is no longer available, I don't see any problems...

You can find a copy of the change log at:

http://www.huv.com/smalltalk/browser.zip

This is the change log from an image where we filed in the browser code.

I can provide an image with it loaded, if you have VS.

Later, Jon

---

Jon Hylands Jon@huv.com http://www.huv.com/jon

Project: Micro Seeker (Micro Autonomous Underwater Vehicle) http://www.huv.com

Jon Hylands wrote:

On Sat, 13 Mar 2004 14:54:20 +0100, "rrobbes" rrobbes@info.unicaen.fr

...

Is the code lying down somewhere (and adequatly licensed), so that someone could do the porting effort ?

Well, I have the code

More importantly: do you have the copyright?

and since The Object People doesn't exist anymore,

doesn't mean that the code is in the public domain

and this was never an official product that they were selling or offering to clients,

doesn't matter at all

and its written for a Smalltalk that is no longer available, I don't see any problems...

Copyright issues can become very nasty, as the SCO case shows. Someone had the rights to that code and in all probability still holds it. Companies are owned by people, and even if a company vanishes, that company's assets are kept or reassigned. If the proposition is to include something from an external source in Squeak, then we should make sure we have a bulletproof license that let's us do with it what we want to do. To do otherwise leads to incalculabe financial risks, because the copyright owner may one day - quite rightfully - decide to exert his rights and claim damages for unauthorized use.

Regards, Lothar

On Mar 14, 2004, at 11:52 AM, Jon Hylands wrote:

I agree with you in general, but this code is useless in Squeak, so its really not an issue. This code will be used as a template to rewrite the browser in Squeak.

Even the word "template" is a bit too strong. I'm going to examine it for features that might be useful in OmniBrowser, but I'd be astounded if even the outline of the code could be applied. OmniBrowser is very different from usual ways browsers are implemented.

I speak only for myself, of course, others may be interested doing in a Squeak version that's more faithful to the original.

Colin

2. Suppose you meant to make a class method, but you forgot to hit class

and wind up entering it as an instance method. Is there an easy way to tell squeak "hey, this is currently an instance method, but that's not right, just move this over to the class side?" (i.e. without cutting and pasting the code and all that)

Hi Aaron,

Have you tried the refactoring browser ? I don't remember it having such a refactoring, but that might be doable... Anyways it has a lot of related stuff, such as the possibility to extract methods, inline them, rename variable ...

Romain

Hi all!

"Andreas Raab" andreas.raab@gmx.de wrote:

Hi Goran,

...

If not - then it truly disappoints me, I really thought this community was... capable of constructive cooperation instead of petty "No, I don't like this or that!" or "Forget it, no point..."

As always, these issues need to be ultimately decided between the people actually doing the work. If you ask on a list with a thousand people subscribed you will get a thousand answers. And the people actually doing the work, will just say "forget it no point" as they are busy getting actual work done.

Yes, in general that is true. But we are trying to form a decision process in general in this community and I am a Guide - in short I want to be able to have the community decide things together. Don't we all? Isn't that one of my duties as a Guide?

If the answer to everything is "Don't bother with the community, just code and do things in private" - then there IS no community.

And yes, it really pisses me off that I have to write this meta-reply to the list, if you would have sent that message to me just asking "hey, can't you fix B3D to follow these rough guidelines" I would've done it no questions asked.

Sorry, but I can't email privately to every one of the standard package maintainers. And besides - no, I truly doubt you would have done it "no questions asked". And nor would the other maintainers have done either. I am no God here that can just tell people what to do - and besides I don't *know* what rough guidelines are best - that was why I brought it up in the first place!

So to back up a bit - I am *SIMPLY* saying exactly *THIS*:

- Perhaps it would benefit the quality of the standard packages if they follow a few, good, small, simple, perhaps even automatically enforcable coding conventions, do you all agree? (not saying anything about how many conventions we are talking about or what they are - just asking "Should we have them?")

- Ok, if you do agree with that, what do you think might be a few, good, small, simple, perhaps even automatically enforcable coding conventions?

And with enforcable I was talking about things that we either can:

- Automatically detect and then decide how to handle, like for example missing class comments. - Automatically transform, like for example the blank line after the optional method comment and before the code. And note again, I am not talking about the pretty printer - I personally want to read the code *as it was written* because I don't think a pretty printer will be able to format blocks etc in a good way.

I did write in a reply to Colin I think it was, that I dropped this issue - because it felt so hopeless. Now here I am again trying to make myself clear. I don't know what that means. ;)

And also regarding code comments and documentation:

Le me just say that "tomorrow" never arrives. Developers who say "Yeah, that code is a bit sloppy - but I will write the comments when it is finished tomorrow." are simply self delusional. There is no tomorrow. Tomorrow you are sitting hacking on some other code that is fun and cool. And the rest of us are trying to understand the code you wrote yesterday.

Good comments should be written when the code is written IMHO. I surely don't live perfectly by that rule, but I don't deny that it is so.

But now we're sitting here in these meta-cyclic completely nonsensical discussion where everyone (including you) knows that absolutely nothing substantial will come out of it ;-(

No, that is not true. I hope. One thing has already come out of it - see Ken's announcement on the list yesterday.

Just because the people expressing their opinions will be largely disjunct from the people doing the work.

Sure, that is a risk of course. But still - this is an open project. :)

Dropping out now. If you want me to fix up something in B3D just ask.

Hehe, *that* was a smistake. :) How about:

- Removing the extra spurious release you have on SM with the exact same download file AFAICT. Must be a mistake. - Writing the 70 missing class comments in B3D? ;) Or actually, the 52 in Balloon would be better to start with. :)

Cheers,

• Andreas

Cheers, Göran

PS. Happy again, sorry for getting a bit grumpy in the previous postings.

Doug Way writes:

For example, I think we could agree that enforcing a class comment could be on the list. The only person objecting somewhat to this (Lex) agreed that it would still be a reasonable standard... I don't think anyone else objected.

Well commented or well sunit tested might be better. Personally, I find tests more helpful when returning to code.

Well, Lex is not alone but he argued much more coherently and with more authority than I could.

More useful and used documentation would definitely be a good thing.

Bryce

John Pfersich jp1660@att.net wrote:

I not only think that it's not only not pointless to try, but that it's necessary to succeed. And I can't see why any package that will be included in the base can't conform to the standards.

We first need to determine what the standards, if any, should be. I dearly want any such standard to only be adopted if we are convinced it will improve things. The class comments rule has such an argument, but most of the other proposed rules do not. If we adopt rules just to have consistency, then we are just tying our own hands.

General judgement and taste can go a long way without needing any rules. We do not necessarily need to have a list of rules to follow. It is sufficient to have people with good taste guarding the entry.

On the flip side, bad code cannot be made good just by forcing it into some conventions. Do we want to have to accept code just because it follows some list of rules? I don't think so -- we should also require that the most important packages have a certain level of functionality and quality, for example. There is no safety to be found in lists of rules; poor authors will always find a new abheration to circumvent them. :)

Okay, that's my general philosophy. On the specific issue of coding conventions, I get the impression that we are getting along fine without them, so I'd tend to hope we just leave things the way we are. Maybe I'm mistaken, but from reading this thread I've not heard of people having particular problems reading Squeak code, especially since they can fall back on the pretty printer when necessary. However, if I'm wrong, and people are having trouble, then indeed let's adopt some conventions to help out. I just want to see some expected benefit from it.

The rules I *really* think we should have are general and high level. For example, we might say "packages should be documented well enough that most people who know the domain can figure out how to use the package."

-Lex

Hi goran

for the few rules we can agree on:

1- class comment stating the key collaborations and responsibilities of the class (not jsut in plain english the text of the class) with one example (even if tests will cover the rest).

2- method indented like that:

myCoolMethod: anArgument "a cool comment if any"

my wonderful code nicely indented.

I think that this is the basic minimal stuff we can agree on. So lets move on. Stef

Hi all!

Funny, seems I can't let go of this, even though it feels so hopeless...

"Lex Spoon" lex@cc.gatech.edu wrote:

Lex wrote:

...

...

On the flip side, bad code cannot be made good just by forcing it into some conventions. Do we want to have to accept code just because it follows some list of rules? I don't think so -- we should also require that the most important packages have a certain level of functionality and quality, for example. There is no safety to be found in lists of rules; poor authors will always find a new abheration to circumvent them. :)

Hmm, not sure if I replied to this before - but who ever said we should "have to accept code just because it follows some list of rules"? Of course not, that is just silly.

goran.krampe@bluefish.se wrote:

...

Personal reflection: I find it interesting that so many - at least considering the vocal people - are so negative about trying to establish small little rules. We do it all the time! The mistake I did this time was obviously to *ask* about it. ;)

This is important to me. Most rules will not improve the situation--they'll just make more rules. If you want to make things better then someone has to go in and make some positive effort. Rules are negative efforts that merely say what people cannot do.

Or what they *should* do. Not all rules are "negative". Often the difference is in the eyes of the beholder.

Also - there are tons of Smalltalk coding conventions that we *do* follow and that most of us would get upset about if they were not adhered to in the standard packages. Now, most of these rules are so "obvious" we don't bother listing them. And that is fine, no need to clutter our minds with rules on stuff that everyone follow.

And then there are the things that people do differently. And that is the area where it gets interesting.

On coding conventions, I do not want to reject code merely because it disobeys some arbitrary coding convention. That sounds like a net minus, given that we can all read the existing code fine, but a new contributor may well not be hip with the conventions.

Funny you mention a "new contributor". You do realize that it will be much easier for new contributors if the standard packages follow the same conventions? It will then of course minimize the problem. Doing as the Romans will be much easier when Rome is clearly visible.

And also - I have always talked about these new rules to be easily enforceable and probably also very easy to apply. Which means that it would not lead to rejections.

I am sorry if I am sensitive about this, but I see it in Debian and I see it in the laws of my country. People pile on rules in order to try and protect themselves from bad stuff, but it doesn't work. Life always has danger, and bad coders will always astound you with a new abberation. The criterion for a good rule (or a good law) is that it improves things on the whole when it exists, not that it corresponds to good practice.

If I didn't believe having *some* rules could lead to an improvement I would never have suggested it. Also - we have *no* spoken rules today (only a big heap of unspoken ones) and you are already reacting against it.

In that case I can only interpret your view as "I don't want any rules".

Rules are a good tool for a community to use, but the tool must be used with care. Let's make just a few rules, let's choose them carefully, and let's *not* have lots of small rules. Let's hack code, not policy docs.

Eh... a few rules, chosen carefully. What do you think I have been asking for?

By the way, if you truly have made policy without asking, I am unaware of it and I do not feel compelled to comply.

Being the main drive behind SM and also a Guide I have been involved in making tons of "rules". Lots and lots of them.

But if I instead say that I have "openly made decisions on how things should work with the input from the community" - then perhaps I am not triggering the same sensitive buttons. Still the same.

-Lex

This discussion has actually made me lose some of my faith in this community. I thought we were striving for excellence. I thought we were collectively trying to move Squeak into a future were it is a superb universal tool for novices and pros alike. Having consistency in the standard code - when such consistency improves both the impression of quality and actual readability - felt to me like a quite obvious path for us to explore.

It turned out that even the most obvious thing - like having a class comment for all standard classes - was something that I had to fight for! Here Tim would insert a witty on-the-mark expression, but since I am not Tim I just write:

Silly. faith := faith - 10.

regards, Göran

Hi Lex!

"Lex Spoon" lex@cc.gatech.edu wrote:

goran.krampe@bluefish.se wrote pages of text such as:

...

In that case I can only interpret your view as "I don't want any rules".

Just one more post, because this is getting really silly. I am not just arguing for its own sake, and it is rude and presumptious of you to suggest this. My time is limited and I spend it carefully.

Lex, I don't think you are arguing for its own sake - and I did not mean that. I was just trying to make sense of it all, see below.

I wrote:

...

abberation. The criterion for a good rule (or a good law) is that it improves things on the whole when it exists, not that it corresponds to good practice.

If I didn't believe having *some* rules could lead to an improvement I would never have suggested it. Also - we have *no* spoken rules today (only a big heap of unspoken ones) and you are already reacting against it.

In that case I can only interpret your view as "I don't want any rules".

What I meant is that I am asking if we should set up a few rules and what they in that case should be. And AFAICT you are as a response pointing out the dangers of piling rules on top of each other. I just felt *that* was a tad strong reaction when I was just asking for a few rules especially since we don't have *any* right now.

So me asking for a few rules, when there are *none* - and your reaction, led me to that interpretation. I was more expecting you to reply in the lines of "No, of course not - I mean this...".

regards, Göran

PS. I am glad to see that the criterion you mentioned above is one that I myself wholeheartedly agree with. So I really don't think we are disagreeing that much - we just happened to get off wrong here or something.

"Lex Spoon" lex@cc.gatech.edu wrote:

...

Perhaps this should be expanded so that uncommented methods (perhaps testing for more than a smallish number of bytecodes?) also have such a comment automagically added? Since we have the writers initials (normally) we could even make it be something like

Interesting idea, but IMHO no. I don't even quite agree that every class needs a comment; if you see this class hierarchy:

LambdaExpression LEVariable LEApplication LEAbstraction Then it is utterly pointless to go through putting comments like "a LEVariable is a lambda expression variable" and "a LEApplication is a lambda expression application". If you know what a lambda expression then you don't want a comment in the subclasses.

How can you say "don't want a comment"? Are they somehow hurting you? Btw, I remember I think what a LambdaExpression is, though I wouldn't off hand know what the hell an LEApplication is compared to an LEAbstraction. Why not give me a hand and telling me in the class comment?

The name suffices. Or how about this one:

LargeInteger LargePositiveInteger LargeNegativeInteger Sure, put a comment in LargeInteger to say what "large" means. But a comment would be useless in the two subclasses.

First of all this is not how those classes look - but I assume it is hypothetical. Furthermore I find the class comments of the existing classes to be perfectly fine - the one in LargeNegativeInteger tells me that "there is nothing special to know here, move on please". Perfect.

Still it would be interesting to know for example if an instance of LargePositiveInteger is identical to a LargeNegativeInteger except for its class - which it is btw.

But it doesn't matter - if there is no class comment in there I would still be left wondering if:

- It has been lost. - The author was sloppy. - If it is intentionally left blank.

So why not put a single line in there as it is btw in LargeNegativeInteger?

With methods it's even more frequently the case that a comment is a wasted distraction and an unnecessary maintenance burden. We really don't need a lot of this kind of comment:

sillify: aString "sillify the argument"

I don't think anyone has argued that.

regards, Göran

"Lex Spoon" lex@cc.gatech.edu wrote:

goran.krampe@bluefish.se wrote:

...

"Lex Spoon" lex@cc.gatech.edu wrote:

...

Interesting idea, but IMHO no. I don't even quite agree that every class needs a comment; if you see this class hierarchy:

LambdaExpression LEVariable LEApplication LEAbstraction Then it is utterly pointless to go through putting comments like "a LEVariable is a lambda expression variable" and "a LEApplication is a lambda expression application". If you know what a lambda expression then you don't want a comment in the subclasses.

How can you say "don't want a comment"? Are they somehow hurting you? Btw, I remember I think what a LambdaExpression is, though I wouldn't off hand know what the hell an LEApplication is compared to an LEAbstraction. Why not give me a hand and telling me in the class comment?

Yes, they hurt, though not much. Here are a few ways:

1. They are extra maintenance. Any change to those classes must now

modify the comments, too, to keep up.

Hehe, yes. But that argument is kinda silly IMHO. Because it would be an argument for not writing any documentation at all. I mean, why take on the hassle of maintaining it?

2. They are an extra source of bugs. Wrong comments are bad.

And again, only if they are indeed wrong. I mean, both these arguments are only saying "Comments are bad because it will take time and effort for me to keep them in shape". IMHO silly.

3. They easily duplicate effort. It is better to comment things in one

place and where necessary to have links to that one place.

Definitely. And I have never said that class comments should be duplicated. A reference is perfectly fine IMHO.

BTW, I intentionally picked an obscure example. The point is that you if you don't know what a lambda expression is then you have no hope of dealing with a l.e. "abstraction". Thus you really need to go read the LambaExpression comment, first.

So you mean that the information about LEAbstraction and LEApplication is in the superclass?

Sure, I can sympathize with that way of doing it - I would still like one line saying "See superclass." because then I can be certain that you didn't forget to write it nor did it get lost somewhere (which has happened).

Let me step back and mention two perspectives I am coming from.

First, I view reading a Smalltalk program as an exploration. The programmer knows certain things, and they probe into the system to learn ever more. There are many different ways to probe into the system, and I try to keep this in mind when I write code. I do not expect any individual part of the code to document the entirity; the code is itself a document.

I agree with all this. As long as it doesn't turn into an excuse for not writing suitable comments.

In this particular example, I would expect people who are looking at a class deep within a hierarchy, to take a peek at the superclasses in order to orient themselves. This is so automatic that I don't think every subclass in the system should even need a specific link mentioned in the comments.

I repeat the "Is it blank intentionally or did Lex just forget to write it?"-argument.

Do we really want, for example, every subclass of Morph to say "see the Morph superclass for more info" ?

Hopefully they have more to say than that. And if they don't then yes - I would like a single line in there that someone wrote *intentionally*. As a matter of fact, I don't care what it says - as long as it is there.

IMHO, such a comment is just as wasted as this one:

x := x + 1. "add 1 to x"

This comment adds nothing to me as a reader because I am already looking at the line in question and the code is obvious. But the same is not true for a blank class comment for reasons I have already explained.

Second, any rules cause some chaffing. I have been watching Debian amass larger and larger piles of policy, and it saddens me. I *like* having individuals use their own taste, and I like having the freedom to explore my own style. Every rule cuts away style possibilities, however small they may seem. Further, every rule, no matter how innocuous it appears, is a chance to get it horribly wrong and thus end up very annoying to lots of people. Thus I have a general tendency to avoid global rules as much as we can.

And I agree with all this. Still want to reflect on it.

regards, Göran