Info on Smalltalk DSLs or Metaprogramming...
Locked
123456
... 10
123456
... 10
 
|
> But no matter how you get them here, it wouldnt matter one
> bit today because they wont stay. Why? Because smalltalk > documentation is like a ghost town. > When I found whysmalltalk.com (shows up #4 if you google "smalltalk > tutorial") I was excited about all the examples and > tutorials. After 90% of the links pointed nowhere I started > doing searches on the net to find out if I was simply too > late, maybe smalltalk was dead already. And your own squeak > site isn't much better. Nothing screams "no one lives here anymore" > like dead links. And the more dead links the loader the scream. > > And dont go down the road that "smalltalk is simple so the > code documents itself". The code NEVER documents itself, > that is a cop-out and a bold face lie. If you don't want to > document then for God's sake, hand it off to someone who > will. Not every single method ever of course, but anything > the API user uses directly should be documented. > > And it needs to be consistant too. I'm a "digger", if it is > there I will find it. But most people aren't. If your > solution is "well go to the class side, there is maybe some > method there that documents the class" then you don't have a > solution. "Documentation is always on the class side in the > 'documentation' protocol (and here is how you find that)" > would be much better. > > You have a very friendly mail list, the best I've ever seen > to be honest. > But that doesn't overcome documentation. People are not > trained to look on mailing lists for documentation. When > thinking about users you have to think Homer Simpson. You > can scream "look in the news groups" on every page and he > will say "Thanks, what is the link to/program that shows the > documentation?". > > I hope someone somewhere finds something I said useful. :) Great post, but one comment. I used to feel the same way, until I realized sample code is the best documentation there is, and alt + n on any method pulls up every reference to that method in the image providing me with plenty of examples of that method in use. The browsers and code have become THE documentation to me at this point and I rarely find I need, or want, anything more than that. I don't think it's a cop out or a lie to say the code is self documenting, it's simply a point of view one comes to hold after working in Smalltalk long enough. |
RE: Info on Smalltalk DSLs or Metaprogramming...
|
|
In reply to this post by Rich Warren
> Part of the problem is different people seem to have
> different interpretations of what a DSL is. In some > definitions, any significantly complicated project becomes a > DSL (or at least any well- written project). This is the definition I think most of us have. We should be more explicit and call them embedded DSL. Lispers write DSL's with macro's, bending lisp to the problem domain, but it's still valid Lisp. Smalltalker's write DSL's with blocks and Objects, also bending the language to the problem domain, but it's still valid Smalltalk. There's value in making a distinction between a DSL, and an embedded DSL, Lispers and Smalltalkers generally mean embedded DSL when they say DSL. They're talking about extending the language, as is, without changing it's syntax. > When I spoke about DSLs, I was particularly talking about > reading in and evaluating text files. I don't think that is a good definition of a DSL. Files are orthogonal to the issue of DSL or not DSL. You seemed hell bent on using a syntax that wasn't valid Smalltalk, and I understood you pretty much as Ralph did, and wondered, why? Yes, this is building a DSL, but it's building a custom DSL that requires parsing. While a valid approach, it's certainly not the easiest or most practical solution, which is all the Smalltalkers were getting at. Even if you did want to build a custom DSL, the practical approach would be to prototype it as an embedded DSL first, get it working, and then decide after that, if a custom syntax would be useful. Just my $.02 |
|
|
In reply to this post by Ramon Leon-5
>Great post, but one comment. I used to feel the same way, until I realized >sample code is the best documentation there is, and alt + n on any method >pulls up every reference to that method in the image providing me with >plenty of examples of that method in use. The browsers and code have become >THE documentation to me at this point and I rarely find I need, or want, >anything more than that. I don't think it's a cop out or a lie to say the >code is self documenting, it's simply a point of view one comes to hold >after working in Smalltalk long enough. I do agree completely, even though i m working in smalltalk from few months. And regardlessly Smalltalk code in Squeak image is really much more readable than most languages libraries. -- Hiren J.Thacker(www.jroller.com/page/daredevil) [sorry for very bad english :D] |
|
|
I seem to be off the list at the moment or missing messages so I
missed the first post apparently. The fact is, no matter how obvious the language is there are patterns we use. Sure in some instanses the method can be obvious enough to be understood. But there are plenty of OO patterns that are not obvious if you have not seen them before and sometimes even if you have. You may be able to read from the code what it is doing, but you are going to be thinking "why in the world is he doing this?". Also, if you work with a pretty complicated subsystem (i.e. uses lots of underlying objects to get work done) do you really find it a good solution to dig through class after class after class just to find out what an interface (i.e. what the subsystem end users use) method does? And even if you do, someone new to the language isn't. And must every usage of a new subsystem be a trip through every method in that system? Can't I just get a list of what the useful methods are and how to use them? I appreciate the simplicity of the language, but it is because of this reason one must guard against the false feeling of "self documenting code". You don't have to document every method ever, but ANY interface to the subsystem should be documented some how and any method over a certain number of lines should be documented. Even if you coded right in pure english, I still wouldn't know *why* you did it the way you did, and therefor I wouldn't know *why* I shouldn't just change it. >From: "Hiren Thacker" <[hidden email]> >Reply-To: The general-purpose Squeak developers >list<[hidden email]> >To: "The general-purpose Squeak developers >list"<[hidden email]> >Subject: Re: Thoughts from an outsider >Date: Wed, 30 Aug 2006 23:17:20 +0530 > >>Great post, but one comment. I used to feel the same way, until I >>realized >>sample code is the best documentation there is, and alt + n on any method >>pulls up every reference to that method in the image providing me with >>plenty of examples of that method in use. The browsers and code have >become >>THE documentation to me at this point and I rarely find I need, or want, >>anything more than that. I don't think it's a cop out or a lie to say the >>code is self documenting, it's simply a point of view one comes to hold >>after working in Smalltalk long enough. > >I do agree completely, even though i m working in smalltalk from few >months. >And regardlessly Smalltalk code in Squeak image is really much more >readable >than >most languages libraries. > >-- >Hiren >J.Thacker(www.jroller.com/page/daredevi<http://www.jroller.com/page/daredevil> >l) > >[sorry for very bad english :D] > |
|
|
> The fact is, no matter how obvious the language is there are
> patterns we use. Sure in some instanses the method can be > obvious enough to be understood. But there are plenty of OO > patterns that are not obvious if you have not seen them > before and sometimes even if you have. You may be able to > read from the code what it is doing, but you are going to be > thinking "why in the world is he doing this?". > > Also, if you work with a pretty complicated subsystem (i.e. > uses lots of underlying objects to get work done) do you > really find it a good solution to dig through class after > class after class just to find out what an interface (i.e. > what the subsystem end users use) method does? And even if > you do, someone new to the language isn't. This is the difference between using a framework and using an API, Smalltalkers like frameworks, which by their very nature, require you to understand how they work. You make it sound like digging through classes is hard, it's just a couple keystrokes, browse here, browse, there, check out a few examples, bam, ok, makes sense now. I not only find digging through classes a good solution, I find it's the only one I've ever found that works. Documents lie, code doesn't. I consider understanding how something works, a prerequisite to using it well. And frankly, I can bounce around the code, in a far more organized and faster manner than I could through some document. > And must every usage of a new subsystem be a trip through > every method in that system? Can't I just get a list of what > the useful methods are and how to use them? If you have a task to perform, you should be able to just browser class names to see who might do that, it's a simple task to quickly check a class for it's responsibilities. Well designed frameworks make this a breeze. As I said earlier, getting a list of the useful methods and how to use them, is only a hotkey or two away. > I appreciate the simplicity of the language, but it is > because of this reason one must guard against the false > feeling of "self documenting code". You don't have to > document every method ever, but ANY interface to the > subsystem should be documented some how and any method over a > certain number of lines should be documented. > > Even if you coded right in pure English, I still wouldn't > know *why* you did it the way you did, and therefore I > wouldn't know *why* I shouldn't just change it. > Self documenting code is not a false feeling, it's a point of view. Smalltalkers in general don't write long methods, so that's not an issue. I find class and method comments, totally sufficient for me to grok how a system works, a quick look at the hierarchy browser, couple of samples of those classes in use, and away I go. I usually find when something is done weird, there is a comment explaining why it was done that way right there in the code, as it should be. I appreciate that some people want more documentation, that's a valid point of view, but let's not insist that those of us who think the many browsers, classes, categories, method categories, and class and method comments are sufficient documentation are somehow foolish, we're not. Some people need instructions on how to assemble things, others just look at the parts, tinker a bit, and figure it out, Smalltalk is wonderful for those in the latter camp. I'll take being able to look directly at the class over looking at a document any day of the week, it's the best documentation there is as far as I'm concerned. |
|
|
I'm not trying to say you're a fool. It is great that this
method works for you. But do you want smalltalk to be for people who tinker or do you want a larger user base? Larger user base buys you more bodies to write code so things get done faster, new killer apps get made. It also buys you more testers and potential bug fixers. I just don't find "code is the documentation" acceptable at a professional level. Open software tried to say that in the beginning and they were shot down (any that wanted to make money anyway). If you want to play around, take your watch apart to see how it tells time, ok. But if my company has millions of dollars riding on your software there had better be some documentation. Do really think it would be ok to deliver a product to a customer and say "well, the code is all there, dig around and you should be able to figure out how it works in no time"? >From: "Ramon Leon" <[hidden email]> >Reply-To: The general-purpose Squeak developers >list<[hidden email]> >To: "'The general-purpose Squeak developers >list'"<[hidden email]> >Subject: RE: Thoughts from an outsider >Date: Wed, 30 Aug 2006 11:35:42 -0700 > > > The fact is, no matter how obvious the language is there are > > patterns we use. Sure in some instanses the method can be > > obvious enough to be understood. But there are plenty of OO > > patterns that are not obvious if you have not seen them > > before and sometimes even if you have. You may be able to > > read from the code what it is doing, but you are going to be > > thinking "why in the world is he doing this?". > > > > Also, if you work with a pretty complicated subsystem (i.e. > > uses lots of underlying objects to get work done) do you > > really find it a good solution to dig through class after > > class after class just to find out what an interface (i.e. > > what the subsystem end users use) method does? And even if > > you do, someone new to the language isn't. > >This is the difference between using a framework and using an API, >Smalltalkers like frameworks, which by their very nature, require you to >understand how they work. You make it sound like digging through classes >is >hard, it's just a couple keystrokes, browse here, browse, there, check out >a >few examples, bam, ok, makes sense now. I not only find digging through >classes a good solution, I find it's the only one I've ever found that >works. Documents lie, code doesn't. I consider understanding how >something >works, a prerequisite to using it well. And frankly, I can bounce around >the code, in a far more organized and faster manner than I could through >some document. > > > And must every usage of a new subsystem be a trip through > > every method in that system? Can't I just get a list of what > > the useful methods are and how to use them? > >If you have a task to perform, you should be able to just browser class >names to see who might do that, it's a simple task to quickly check a class >for it's responsibilities. Well designed frameworks make this a breeze. >As >I said earlier, getting a list of the useful methods and how to use them, >is >only a hotkey or two away. > > > I appreciate the simplicity of the language, but it is > > because of this reason one must guard against the false > > feeling of "self documenting code". You don't have to > > document every method ever, but ANY interface to the > > subsystem should be documented some how and any method over a > > certain number of lines should be documented. > > > > Even if you coded right in pure English, I still wouldn't > > know *why* you did it the way you did, and therefore I > > wouldn't know *why* I shouldn't just change it. > > > >Self documenting code is not a false feeling, it's a point of view. >Smalltalkers in general don't write long methods, so that's not an issue. >I >find class and method comments, totally sufficient for me to grok how a >system works, a quick look at the hierarchy browser, couple of samples of >those classes in use, and away I go. I usually find when something is done >weird, there is a comment explaining why it was done that way right there >in >the code, as it should be. > >I appreciate that some people want more documentation, that's a valid point >of view, but let's not insist that those of us who think the many browsers, >classes, categories, method categories, and class and method comments are >sufficient documentation are somehow foolish, we're not. Some people need >instructions on how to assemble things, others just look at the parts, >tinker a bit, and figure it out, Smalltalk is wonderful for those in the >latter camp. I'll take being able to look directly at the class over >looking at a document any day of the week, it's the best documentation >there >is as far as I'm concerned. > > |
|
|
In reply to this post by Ramon Leon-5
> Even if you coded right in pure English, I still wouldn't > know *why* you did it the way you did, and therefore I
> wouldn't know *why* I shouldn't just change it.
actually many seniour Squeakers r thr always on #squeak at irc.freenode.net or asking on mailing-list also get very quick reply usually.So i think we can ask, to author or anyone who knows, about *why* you did it the way you did usually. |
|
|
In reply to this post by J J-6
> I'm not trying to say you're a fool. It is great that this
> method works for you. But do you want Smalltalk to be for > people who tinker or do you want a larger user base? Larger > user base buys you more bodies to write code so things get > done faster, new killer apps get made. > It also buys you more testers and potential bug fixers. I don't measure success by the number of people using Smalltalk. Personally, I want Smalltalk to be for people who grok Smalltalk, not for people who want to make it more popular by making it more like everything else. Smalltalk rocks precisely because it's not like everything else, and that includes what is considered programmer documentation. Self documenting code is a style, one smalltalkers prefer, that and some unit tests, are the best documents there are. > I just don't find "code is the documentation" acceptable at a > professional level. Open software tried to say that in the Ok, maybe you don't, but many others do. There's lot's of stuff being done out there in Smalltalk land with little or no "formal" documentation. Documentation the way you define it, simply isn't necessary for success, maybe it's necessary for mass accpetance, but acceptance and success are different things. Smalltalk is already successful, and growing more so every day. > But if my company has millions of dollars riding on your > software there had better be some documentation. That's an opinion, not a fact, but there's plenty of code out there running on Squeak, and very little if any formal documentation. Success depends on people, not paperwork. You'd be trusting millions of dollars to a person, or a team of people, not some papers. > Do really think it would be ok to deliver a product to a > customer and say "well, the code is all there, dig around and > you should be able to figure out how it works in no time"? I thought we were talking about documenting code for programmers, not user documents for products. Was I mistaken? |
Re: Info on Smalltalk DSLs or Metaprogramming...
|
|
In reply to this post by Ramon Leon-5
Though, sometimes part or all of a syntax of a language comes from
other software applications or hardware devices that also represent the domain or work in the domain, which in turn, might be file bound. It's the "make the text user readable/editable" that gives me pause. Having had a course in Linguistics, I know that the meanings we apply to these symbols are greatly subject to various interpretations and misinterpretations, especially when we begin to cross cultures and cross into non-roman native speakers... just as the same is true with body language across cultures. Quick, what's the most user recognizable body gesture for agile style updates? Or, letting someone know their performance has a social bug, that that they have a bug on them? Your chosen language will make your users dependant on whatever device and software generates and manipulates that text. One syntax & use of white space might be better for manipulation by VI editors, another for eMacs editors, and another for Slickedit or something custom built, etc. In reality any GUI is really a domain specific language but is almost never treated as such. It's just not a text language; it's a gesture language with a syntax and vocabulary of gestures and shapes. My money would bet that the best use of time would be spent first learning what interface tools and applications the domain user must use, wants to use, likes to use, is open to your suggestions to distribute and use, and then make the domain language leverage the strengths of those tools in matching and manipulating the various aspects and features of the domain itself. If you have the opportunity to make or require a certain tool, then rather than find the *lowest* common denominator for all tools, you mould the interface to the domain. You can then customize the interface tool to match the various types of users ... graphical visual learners, auditory learners, kinesthetic learners, sequential learners, vector learners, "systems theory" learners, as well as text learners. Regarding text, as an old, wise programmer once told me, "Nobody reads a 1,000 page report." Every interface and language (spoken or otherwise) is all about collapsing/folding/labeling the data for convenient transportation, manipulating, storage/remembering, and retrieval. Text alone just doesn't scale. Cheers, Darius [|] Powered and Empowered by Smalltalk |
|
|
In reply to this post by Ramon Leon-5
>From: "Ramon Leon" <[hidden email]> >Reply-To: The general-purpose Squeak developers >list<[hidden email]> >To: "'The general-purpose Squeak developers >list'"<[hidden email]> >Subject: RE: Thoughts from an outsider >Date: Wed, 30 Aug 2006 12:19:52 -0700 > > >I don't measure success by the number of people using Smalltalk. >Personally, I want Smalltalk to be for people who grok Smalltalk, not for >people who want to make it more popular by making it more like everything >else. Smalltalk rocks precisely because it's not like everything else, and >that includes what is considered programmer documentation. Self >documenting >code is a style, one smalltalkers prefer, that and some unit tests, are the >best documents there are. > I don't want smalltalk to be like everything else. But I do want language choice where I work, and that doesn't happen if the language doesn't have a very big user base. I don't think actually documenting your work will turn smalltalk instantly into Java. > > I just don't find "code is the documentation" acceptable at a > > professional level. Open software tried to say that in the > >Ok, maybe you don't, but many others do. There's lot's of stuff being done >out there in Smalltalk land with little or no "formal" documentation. >Documentation the way you define it, simply isn't necessary for success, >maybe it's necessary for mass accpetance, but acceptance and success are >different things. Smalltalk is already successful, and growing more so >every day. > Well I certainly hope it gets more sucessful every day. It certainly deserves it IMO. > > But if my company has millions of dollars riding on your > > software there had better be some documentation. > >That's an opinion, not a fact, but there's plenty of code out there running >on Squeak, and very little if any formal documentation. Success depends on >people, not paperwork. You'd be trusting millions of dollars to a person, >or a team of people, not some papers. > Yes, but that isn't the issue. The issue is what if you guys leave? If we have nice, up to date documentation of the system the team I have to get to replace you doesn't have to take as long figuring out the system. > > Do really think it would be ok to deliver a product to a > > customer and say "well, the code is all there, dig around and > > you should be able to figure out how it works in no time"? > >I thought we were talking about documenting code for programmers, not user >documents for products. Was I mistaken? > > No you weren't, but I see the two things as close to equivalant. If you wouldn't give software to end users with no documentation, how could you consider it ok if your end users happen to be programmers? I mean, in the case of a subsystem you are delivering an API, but I want to understand what it does without having to basically read the entire code. I relize smalltalk code writers write small methods, and that is good for the system. But it takes me more time if I have to look up how a method works because the first method (or 3) wont actually be doing the work. |
|
|
In reply to this post by Ramon Leon-5
My single counter point. The code almost never explains how or why
something was deleted /out/ of the code because it was Bad. Don't assume everything in past versions is everything the programmer wrote in that method. Much of what the programmer learned was something he tried/failed and threw away, but which a new user might try /again/ because it was NOT in the code already. All the convenient searching shortcuts begin to fail if you need to find out how code has changed over time as one tries to understand it or how not to redo something bad. The code also rarely tells you that the code which you may "understand" actually has code smell, is a /bad/ example, or is an archaic style of programming. Java may be inconsistent, but so is the Squeak class library... all the way down. Sometimes you can't see the forest for the trees. Cheers, Darius [|] Powered and Empowered by Smalltalk |
|
|
Yes, the version system right as part of the IDE is amazing and powerful.
Perhaps the issue we are having is that you are thinking of someone wanting to change the subsystem, and I am (mostly) thinking of people using the subsystem. I have identified that "X" will do what I want, now I have it downloaded, what do I do with it? Unit tests can give me examples but that isn't very formal, you know? :) (I relize I also mentioned lines of any code over a certain amount, but I can and have been flexable on that point with people I work with). >From: "Darius Clarke" <[hidden email]> >Reply-To: The general-purpose Squeak developers >list<[hidden email]> >To: "The general-purpose Squeak developers >list"<[hidden email]> >Subject: Re: Thoughts from an outsider >Date: Wed, 30 Aug 2006 13:04:19 -0700 > >My single counter point. The code almost never explains how or why >something was deleted /out/ of the code because it was Bad. > >Don't assume everything in past versions is everything the programmer >wrote in that method. Much of what the programmer learned was >something he tried/failed and threw away, but which a new user might >try /again/ because it was NOT in the code already. All the convenient >searching shortcuts begin to fail if you need to find out how code has >changed over time as one tries to understand it or how not to redo >something bad. > >The code also rarely tells you that the code which you may >"understand" actually has code smell, is a /bad/ example, or is an >archaic style of programming. Java may be inconsistent, but so is the >Squeak class library... all the way down. > >Sometimes you can't see the forest for the trees. > >Cheers, >Darius >[|] Powered and Empowered by Smalltalk > |
Re: Thoughts from an outsider
|
|
In reply to this post by Hiren Thacker
On 8/30/06, Hiren Thacker <[hidden email]> wrote:
There are three possible responses when someone makes a complaint: you can address it, you can argue that it's invalid, or you can attack the complainer. I suppose I'm happy that everyone's doing the second rather than the third, but I'd rather we were doing the first. J J is entirely correct. There needs to be more documentation. Smalltalk is extremely readable, and experienced developers can generally figure out fairly quickly how something works through the Message Finder, Senders Of/Implementers Of, etc., but that ignores the fact that I shouldn't have to do that. What takes me and everyone else an hour each of spelunking through the bowels of the class hierarchy would've taken the original designer about thirty minutes to summarize in a few paragraphs. Those paragraphs should focus on both what and why, and the interplay between those. Even if that documentation is slightly inaccurate, if it at least gives me an insight into the mind of the original developer, my code exploration can be faster, more focused, and more rewarding. To take a specific example because I know about it, we routinely get questions on the Seaside list about the difference between the legacy renderer and the newer canvas renderer, because there is no real documentation about what problem canvas was trying to solve, how it goes about solving it, what the abstraction is that allows pluggable renderers, whether the user might want ever to write his own renderer, why canvas is still not the default renderer even though nearly all the libraries require it, or half a dozen other small points. You can answer the how and what by googling the mailing list (if you're lucky enough to use the right terms) or by plowing through the voluminous source code and test suites. Even if you do both, though, you still might miss very basic facts that are basically undocumented if you don't happen to hit just the right email message or look at just the right method in your search. (Either #text: or #with: must be the last message sent, for example, or unexpected things happen.) Meanwhile, if you want the why of canvas, you really need to find a single email from Avi from I-don't-know-how-long ago where he announces that a nascent WAHtmlCanvas will be included in an upcoming Seaside 2.5 alpha release and explains in terms that are perfectly clear to Seaside 2.3 hackers why the newer library will be better. The chance of a new user finding that email, let alone truly understanding and internalizing its meaning without already knowing Seaside, is very low. This problem is obviously not unique to Seaside; thanks to the Seaside FAQ and walkthroughs, Seaside is actually in much better shape than some other packages. I'm harping on it because I'm familiar with it. The problem runs throughout many libraries both in the core of Squeak and in the full image. Hiren proposes you simply email the list whenever you have a why. That's a waste of everyone's time. The developer has to explain more than once, while users who subscribe to the list have to either preemptively save and categorize important emails or else try to remember enough words from the email that they can google their way to it--and frequently, they give up and ask again anyway. New users, meanwhile, are too scared to ask questions on squeak-dev, which is where you'd have to ask if you really wanted the original coder to respond with a because instead of a more experienced user to respond with a how-to. Communities that tell their users to RTFM find themselves alone very quickly. We're telling ours to RTFSC. There has got to be a compromise better than that. --Benjamin |
Re: Thoughts from an outsider
|
|
In reply to this post by J J-6
J J puso en su mail :
> Do really think it would be ok to deliver a product to a > customer and say "well, the code is all there, dig around > and you should be able to figure out how it works in no > time"? When you find such customer ? If the system works, customer never wish know what code you are using, if not, well, one hundred nice write manuals do not save you :) Edgar __________________________________________________ Preguntá. Respondé. Descubrí. Todo lo que querías saber, y lo que ni imaginabas, está en Yahoo! Respuestas (Beta). ¡Probalo ya! http://www.yahoo.com.ar/respuestas |
|
|
No, I meant they application consisted of the user having to
figure out to send a MyApplication show. :) It was meant to be an extreme example of "just read the code". >From: "Lic. Edgar J. De Cleene" <[hidden email]> >Reply-To: The general-purpose Squeak developers >list<[hidden email]> >To: squeakdev <[hidden email]> >Subject: Re: Thoughts from an outsider >Date: Wed, 30 Aug 2006 17:12:45 -0300 > >J J puso en su mail : > > > Do really think it would be ok to deliver a product to a > > customer and say "well, the code is all there, dig around > > and you should be able to figure out how it works in no > > time"? > >When you find such customer ? >If the system works, customer never wish know what code you are using, if >not, well, one hundred nice write manuals do not save you :) > >Edgar > > > > > > >__________________________________________________ >Preguntá. Respondé. Descubrí. >Todo lo que querías saber, y lo que ni imaginabas, >está en Yahoo! Respuestas (Beta). >¡Probalo ya! >http://www.yahoo.com.ar/respuestas > > |
|
|
In reply to this post by Benjamin Pollack
Thanks Benjamin, I was starting to get worried. :)
But the case of seaside is a great example. The guys doing that are pretty busy writing code and contributing to the community. If they don't want to stop and write some doc I can understand, but how do other communities handle this? Can we give the documentation task to someone else? It wont be as efficient as if the original developer wrote it, but it would get done at least. This could be something new users (like myself even) could do to help the community, learn the systems better and contribute before they are ready to start releasing code. >From: "Benjamin Pollack" <[hidden email]> >Reply-To: The general-purpose Squeak developers >list<[hidden email]> >To: "The general-purpose Squeak developers >list"<[hidden email]> >Subject: Re: Thoughts from an outsider >Date: Wed, 30 Aug 2006 16:11:15 -0400 > >On 8/30/06, Hiren Thacker <[hidden email]> wrote: >> >>actually many seniour Squeakers r thr always on #squeak at >>irc.freenode.net or asking on mailing-list also get very quick reply >>usually.So i think we can ask, to author or anyone who knows, about *why* >>you did it the way you did usually. >> > >There are three possible responses when someone makes a complaint: you can >address it, you can argue that it's invalid, or you can attack the >complainer. I suppose I'm happy that everyone's doing the second rather >than >the third, but I'd rather we were doing the first. > >J J is entirely correct. There needs to be more documentation. Smalltalk is >extremely readable, and experienced developers can generally figure out >fairly quickly how something works through the Message Finder, Senders >Of/Implementers Of, etc., but that ignores the fact that I shouldn't have >to >do that. What takes me and everyone else an hour each of spelunking through >the bowels of the class hierarchy would've taken the original designer >about >thirty minutes to summarize in a few paragraphs. Those paragraphs should >focus on both what and why, and the interplay between those. Even if that >documentation is slightly inaccurate, if it at least gives me an insight >into the mind of the original developer, my code exploration can be faster, >more focused, and more rewarding. > >To take a specific example because I know about it, we routinely get >questions on the Seaside list about the difference between the legacy >renderer and the newer canvas renderer, because there is no real >documentation about what problem canvas was trying to solve, how it goes >about solving it, what the abstraction is that allows pluggable renderers, >whether the user might want ever to write his own renderer, why canvas is >still not the default renderer even though nearly all the libraries require >it, or half a dozen other small points. You can answer the how and what by >googling the mailing list (if you're lucky enough to use the right terms) >or >by plowing through the voluminous source code and test suites. Even if you >do both, though, you still might miss very basic facts that are basically >undocumented if you don't happen to hit just the right email message or >look >at just the right method in your search. (Either #text: or #with: must be >the last message sent, for example, or unexpected things happen.) >Meanwhile, >if you want the why of canvas, you really need to find a single email from >Avi from I-don't-know-how-long ago where he announces that a nascent >WAHtmlCanvas will be included in an upcoming Seaside 2.5 alpha release and >explains in terms that are perfectly clear to Seaside 2.3 hackers why the >newer library will be better. The chance of a new user finding that email, >let alone truly understanding and internalizing its meaning without already >knowing Seaside, is very low. > >This problem is obviously not unique to Seaside; thanks to the Seaside FAQ >and walkthroughs, Seaside is actually in much better shape than some other >packages. I'm harping on it because I'm familiar with it. The problem runs >throughout many libraries both in the core of Squeak and in the full image. > >Hiren proposes you simply email the list whenever you have a why. That's a >waste of everyone's time. The developer has to explain more than once, >while >users who subscribe to the list have to either preemptively save and >categorize important emails or else try to remember enough words from the >email that they can google their way to it--and frequently, they give up >and >ask again anyway. New users, meanwhile, are too scared to ask questions on >squeak-dev, which is where you'd have to ask if you really wanted the >original coder to respond with a because instead of a more experienced user >to respond with a how-to. > >Communities that tell their users to RTFM find themselves alone very >quickly. We're telling ours to RTFSC. There has got to be a compromise >better than that. > >--Benjamin > |
|
|
In reply to this post by Benjamin Pollack
On 8/31/06, Benjamin Pollack <[hidden email]> wrote:
Benjamin, I think you are taking my english in wrong context.I think JJ was talking about "Design level Whys" if you read his that post, which i replied."Design level Whys" are not important for everyone using it.You should try to solve your doubts first by excersing own mind, its not necessary to ask for whenever u have a why. Regards, Hiren Hiren |
|
|
In reply to this post by J J-6
> Communities that tell their users to RTFM find themselves
> alone very quickly. We're telling ours to RTFSC. There has > got to be a compromise better than that. > > --Benjamin I never said documentation was bad, I was simply responding to the invalid accusation that the Smalltalk style of self documenting code is wrong, or that we're copping out or lying made by JJ below... > And dont go down the road that "smalltalk is simple so the > code documents itself". The code NEVER documents itself, > that is a cop-out and a bold face lie. And... > I appreciate the simplicity of the language, but it is because of this > reason one must guard against the false feeling of "self documenting > code". Saying we could use more documentation, is quite different than saying our practices are wrong, or we are lying, or fooling ourselves with false feeling of "self documenting code". Documents mostly don't exist because there's no one writing them, this is after all an open source community and the people in the know are too busy writing code. The entire community, I'm sure, is open to accepting any documentation anyone feels like writing, including JJ. But in a fast moving development effort, like Squeak, Seaside, and many other projects I'm sure, there's always going to be a lack of documentation, that's just life. This isn't some big commercial framework where you can point a finger and say hey, you should have written more documents. Those kind of documents will naturally evolve as the frameworks settle down and start being used more, but don't insult the authors of such frameworks by calling them liars, seriously, be grateful those guys are writing cool stuff for us to use, worry about documents later. |
Re: Thoughts from an outsider
|
|
In reply to this post by J J-6
J J puso en su mail :
> No, I meant they application consisted of the user having to > figure out to send a MyApplication show. :) It was meant to > be an extreme example of "just read the code". Ok. As person trying to teach Squeak and spread word in Spanish world, sure I understand you. And do all what I could, writing some tutorials. One problem is what Squeak changes so quickly what many becomes obsolete between versions. Another one is Squeak is a software equivalent of Swiss Army knife. You have the several spin-offs or forks, like Croquet, Tweak, Sophie, etc. And so different needs as educational, web development, new object programming ideas, etc. But all this opens the chance of write "Learn Squeak in ten days", sell many copies and become rich and famous :) Edgar __________________________________________________ Preguntá. Respondé. Descubrí. Todo lo que querías saber, y lo que ni imaginabas, está en Yahoo! Respuestas (Beta). ¡Probalo ya! http://www.yahoo.com.ar/respuestas |
|
|
In reply to this post by Ramon Leon-5
On 30-Aug-06, at 1:34 PM, Ramon Leon wrote: >> Communities that tell their users to RTFM find themselves >> alone very quickly. We're telling ours to RTFSC. There has >> got to be a compromise better than that. >> >> --Benjamin > > I never said documentation was bad, I was simply responding to the > invalid > accusation that the Smalltalk style of self documenting code is > wrong, or > that we're copping out or lying made by JJ below... > >> And dont go down the road that "smalltalk is simple so the >> code documents itself". The code NEVER documents itself, >> that is a cop-out and a bold face lie. Well I have bit of experience in Smalltalk and I find myself substantially in agreement with JJ here. Sure, senders and implementors are fabulous tools to have but they offer nothing to help understand what is likely to happen with exceptions and very little for Tweak signals etc. No amount of staring at source code will tell you what the author might have *wanted* the code to do, nor what misbegotten changes somebody made after misunderstanding the intent of the code at a later point. Source code tells you what *actually* happens, not what is *meant* to happen. Anybody that tries to tell you that the code does exactly what it it supposed to is almost certainly lying. Comments in methods ought to offer some help in decoding the expectations for the method as a whole, or for parts of the method. Class comments ought to offer a somewhat higher level view of what the class is supposed to do and the limitations it is known to have. Other forms of comments and documentation are needed to give later authors some hope of being able to use, maintain and improve the system. You need tutorial type documentation to offer newcomers to a part of the system a chance of getting some sense of the system before they can even begin to understand the actual code. Adele Goldberg expressed it once as "if the code isn't documented, it doesn't exist" since without reasonable doc there is no way to count the code as usable in the long term. I tend to add the corollary clause "and if it doesn't exist, what did we pay you for?" Another old friend of mine has also coined the rather nice idea of "program the document, don't document the program" to cover a concept of merging doc and code in the tools so that you can write spec, explanation, commentary, examples and limitations mixed in with executable code. It's not hugely different to some aspects of the late Jef Raskin's idea of The Humane Interface (see http:// www.raskincenter.org) and it wouldn't be too awful implemented as a nice document editor that has a style for 'source code' that actually means source code rather than just using a fixed pitch font. Hmm, now where might we find a document editor with intimate associations with a compiler? tim -- tim Rowledge; [hidden email]; http://www.rowledge.org/tim A)bort, R)etry or S)elf-destruct? |
«
Return to Squeak - Dev
|
1 view|%1 views
| Free forum by Nabble | Edit this page |