OrderedCollection new allButLast?
Locked
123
123
 
|
Hi all,
I think it would be nice to have an easier way to modify comments. One or more delta streams for comments only would be neat. (Change a class comment and the system should ask you if this comment should be committed to a delta stream(s), then the harvesting team could review the comments for inclusion or rejection, or when committing code to Monticello the system could ask and harvest comments into the delta stream for later review). The delta stream would be good for this because it would help to put the change into context and eliminate comments that apply to older squeak images. There is no real substitute for the original author comments, but once you spent the time to figure something out, being able to add comments easily may help improve the situation. Ron Teitelbaum > -----Original Message----- > From: [hidden email] [mailto:squeak-dev- > [hidden email]] On Behalf Of Ralph Johnson > Sent: Wednesday, September 12, 2007 8:34 AM > To: The general-purpose Squeak developers list > Subject: Re: Comments > > Note that anybody can add comments to Squeak, just like anybody can > change code. If you think that some code needs comments, write them > and post them as a change to Mantis. In the Mantis issue, indicate > that you are only changing comments. > > -Ralph |
|
|
On Sep 12, 2007, at 5:49 AM, Ron Teitelbaum wrote:
Exactly! Solves the "style" debate as wel. |
|
|
In reply to this post by Ron Teitelbaum
On Sep 12, 2007, at 6:49 AM, Ron Teitelbaum wrote: > Hi all, > > I think it would be nice to have an easier way to modify comments. > One or > more delta streams for comments only would be neat. (Change a > class comment > and the system should ask you if this comment should be committed > to a delta > stream(s), then the harvesting team could review the comments for > inclusion > or rejection, or when committing code to Monticello the system > could ask and > harvest comments into the delta stream for later review). The > delta stream > would be good for this because it would help to put the change into > context > and eliminate comments that apply to older squeak images. > > There is no real substitute for the original author comments, but > once you > spent the time to figure something out, being able to add comments > easily > may help improve the situation. > I feel the system would be dramatically improved by have the capability of Package/Category level comments. Currently, even when a set of classes do have comments, you still have to wade through the classes in order to find out what a good starting place is to use the provided functionality. For small class hierarchies this isn't too bad, but some are quite large :) This creates a great place to document the intention of a system and provide pointers to other pieces of documentation on classes and methods. This would also prevent having to create specific "documentation" classes that do nothing but hold text. For a great example of this, see Steven Swerlings SVI package - it contains copious amounts of documentation, and uses a class (or classes, I don't remember at the moment) to provide access to the docs. But, IMO, it would be better as a category level construct. Would people be interested in such a feature, as long as it could work with Monticello and OmniBrowser, for example? - Brian |
|
|
In reply to this post by Blake-5
On 9/12/07, Blake <[hidden email]> wrote:
> On Tue, 11 Sep 2007 22:19:17 -0700, tim Rowledge <[hidden email]> wrote: > > That sounds good. > > But, really, how do you apply it in practice to something like the read > accessors to "numerator" and "denominator" in Fraction? > > Some accessors really are both necessary, simple and not needing > documentation. General methods as well. Certainly not as many as are currently without comment, but it does exist. |
|
|
In reply to this post by timrowledge
On 12/09/2007, tim Rowledge <[hidden email]> wrote:
> On 11-Sep-07, at 9:57 PM, Jason Johnson wrote: > > It truly is annoying when you look at classes with no comments. > > Writers of classes need to remember that the next person looking at > > the code doesn't have the whole architecture in their head like you do > > so they may not know where to start. > And to repeat repeat myself again again, the original writer won't > have it all in her head after a distraction. > Or a few weeks. Or a vacation. Yes indeed. I tend to write a method comment before I write the code. It helps me to make sure I know what the *intent* of the message is before I start on the implementation. If I find it hard to explain what a method should do that's an indicator that all is not well with my design. BTW, I don't comment all methods, but I certainly comment most methods. -- Make the most of your skills - with OpenSkills http://www.openskills.org/ |
|
|
In reply to this post by Blake-5
Blake wrote:
> But, really, how do you apply it in practice to something like the read > accessors to "numerator" and "denominator" in Fraction? numerator "Integer - The number of parts in a fraction (written above the line of a fraction). See also denominator." ^numerator denominator "Integer - The number of parts that make a whole in a fraction (written below the line of a fraction). Cannot be zero since nothing can be divided into zero parts. See also numerator." ^denominator > Some accessors really are both necessary, simple and not needing > documentation. Numerator and denominator are no such accessors for sure. First, they describe pretty complex objects and just because *you* know what these mean doesn't mean everybody else does. Secondly, the denominator has even exceptional conditions (like that it can't be zero) which is *most definitely* in need of commenting. I'm sorry but your example falls far short of the point you're trying to make. Cheers, - Andreas |
|
|
On 12-Sep-07, at 10:09 AM, Andreas Raab wrote: > Blake wrote: >> But, really, how do you apply it in practice to something like the >> read accessors to "numerator" and "denominator" in Fraction? > > numerator > "Integer - The number of parts in a fraction (written above > the line of a fraction). See also denominator." > ^numerator > > denominator > "Integer - The number of parts that make a whole in a fraction > (written below the line of a fraction). Cannot be zero since > nothing can be divided into zero parts. See also numerator." > ^denominator makes sense to refer to other methods using the linking available from the alt/apple-6 menu->link to method. Obviously it's a bit difficult to display that in an email... Aside from comments for packages, class categories and perhaps method protocols we actually have a lot of good tools already in the image to make the system a lot more readable. How abut we try to use them? tim -- tim Rowledge; [hidden email]; http://www.rowledge.org/tim "How many Kzin does it take to change a lightbulb?" "None. You can scream and leap in the dark." |
|
|
In reply to this post by Andreas.Raab
On Wed, 12 Sep 2007 10:09:23 -0700, Andreas Raab <[hidden email]>
wrote: > Numerator and denominator are no such accessors for sure. First, they > describe pretty complex objects and just because *you* know what these > mean doesn't mean everybody else does. Secondly, the denominator has > even exceptional conditions (like that it can't be zero) which is *most > definitely* in need of commenting. I'm sorry but your example falls far > short of the point you're trying to make. Disagreed. Unless you want to argue the position that part of the Fraction class's responsibility is to teach someone who doesn't know what a fraction is, what a fraction is. (In which case, I still disagree.) It's not just =me= who knows what they are, it's anyone who has any business using the Fraction class. Your class comment for numerator and denominator say nothing that isn't in the dictionary. Let me use a more obscure example: Say I create a voter database for a registrar and I have a variable for the precinct that the voter is in. Should I then, as an accessor comment, explain what a precinct is? Its role in the electoral college? The history of gerrymandering?[1] It's not the job of code comments to explain reality, the language of what being modeled, or common non-code abstractions (like fractions). Code comments should explain where code diverges from reality, where the variables used might be misleading, or where accepted abstractions are changed. For example, SmallInteger and Large*Integer comments usefully point out their limitations, which have nothing to do with the concept of Integers. They don't explain WHY, and go into the concept of the machine word, etc. Ultimately, it's all abstraction, which one could argue demands explanantion of what is being modeled. But at some level, a programmer says, "Yes, I know this variable 'pineapple' isn't =actually= a pineapple, but it's convenient to pretend it is." If you comment EVERYTHING, you end up devaluing the comments that are actually meaningful. And so, the one time the programmer is using "pineapples" to mean "hand grenades" you miss it, because you've grown accustomed to ignoring the comments, which are mostly noise. And from what I've seen, code comment posses often end up adding a lot of noise which is at best useless, and at worst, confusing. ===Blake=== [1] I have provided that sort of basic education in supporting documents and occasionally even in class comments, but it shouldn't be mistaken for any kind of =code= documentation, and is generally a poor substitute for having actual education. |
|
|
Agree with Blake, too many comments kill the comments
While you are at updating the tools, put a href on webster site, wikipedia or something in Fraction (class) comment. Nicolas Blake a écrit : > On Wed, 12 Sep 2007 10:09:23 -0700, Andreas Raab <[hidden email]> > wrote: > >> Numerator and denominator are no such accessors for sure. First, they >> describe pretty complex objects and just because *you* know what these >> mean doesn't mean everybody else does. Secondly, the denominator has >> even exceptional conditions (like that it can't be zero) which is >> *most definitely* in need of commenting. I'm sorry but your example >> falls far short of the point you're trying to make. > > Disagreed. Unless you want to argue the position that part of the > Fraction class's responsibility is to teach someone who doesn't know > what a fraction is, what a fraction is. (In which case, I still disagree.) > > It's not just =me= who knows what they are, it's anyone who has any > business using the Fraction class. Your class comment for numerator and > denominator say nothing that isn't in the dictionary. > > Let me use a more obscure example: Say I create a voter database for > a registrar and I have a variable for the precinct that the voter is in. > Should I then, as an accessor comment, explain what a precinct is? Its > role in the electoral college? The history of gerrymandering?[1] > > It's not the job of code comments to explain reality, the language > of what being modeled, or common non-code abstractions (like fractions). > Code comments should explain where code diverges from reality, where the > variables used might be misleading, or where accepted abstractions are > changed. For example, SmallInteger and Large*Integer comments usefully > point out their limitations, which have nothing to do with the concept > of Integers. They don't explain WHY, and go into the concept of the > machine word, etc. > > Ultimately, it's all abstraction, which one could argue demands > explanantion of what is being modeled. But at some level, a programmer > says, "Yes, I know this variable 'pineapple' isn't =actually= a > pineapple, but it's convenient to pretend it is." > > If you comment EVERYTHING, you end up devaluing the comments that > are actually meaningful. And so, the one time the programmer is using > "pineapples" to mean "hand grenades" you miss it, because you've grown > accustomed to ignoring the comments, which are mostly noise. And from > what I've seen, code comment posses often end up adding a lot of noise > which is at best useless, and at worst, confusing. > > ===Blake=== > > [1] I have provided that sort of basic education in supporting documents > and occasionally even in class comments, but it shouldn't be mistaken > for any kind of =code= documentation, and is generally a poor substitute > for having actual education. > > |
|
|
In reply to this post by timrowledge
On Wed, 12 Sep 2007 10:28:40 -0700, tim Rowledge <[hidden email]> wrote:
> Excellent examples. If possible I'd like to see comments where it > makes sense to refer to other methods using the linking available > from the alt/apple-6 menu->link to method. Obviously it's a bit > difficult to display that in an email... > Aside from comments for packages, class categories and perhaps method > protocols we actually have a lot of good tools already in the image > to make the system a lot more readable. How abut we try to use them? While I've already expressed my objections to Andreas' examples, I agree with this basic sentiment. |
|
|
*YOU* may know what these tools are............ :) |
|
|
No no no - I don't want to learn a tool. That would be boring. I want to build a tool. That will be fun. :-)
On Sep 12, 2007, at 12:59 PM, Steven W Riggins wrote:
|
|
|
On Wed, 12 Sep 2007 13:37:23 -0700, Todd Blanchard <[hidden email]>
wrote: > No no no - I don't want to learn a tool. That would be boring. I > want to build a tool. That will be fun. :-) LOL Exactly! |
|
|
In reply to this post by Steven W Riggins
On 12-Sep-07, at 12:59 PM, Steven W Riggins wrote: > > >>> Aside from comments for packages, class categories and perhaps >>> method >>> protocols we actually have a lot of good tools already in the image >>> to make the system a lot more readable. How abut we try to use them? >> > > > *YOU* may know what these tools are............ :) tim -- tim Rowledge; [hidden email]; http://www.rowledge.org/tim Fractured Idiom:- AMICUS PURIAE - Platonic friend |
|
|
On Sep 12, 2007, at 2:18 PM, tim Rowledge wrote: > > On 12-Sep-07, at 12:59 PM, Steven W Riggins wrote: > >> >> >>>> Aside from comments for packages, class categories and perhaps >>>> method >>>> protocols we actually have a lot of good tools already in the image >>>> to make the system a lot more readable. How abut we try to use >>>> them? >>> >> >> >> *YOU* may know what these tools are............ :) > Well, obviously what is needed here is some comments on the tools... > Example today. SophieVersion008 had an override to versionNumber. No comment on what versionNumber is in the class comment, nor the method in 001 superclass. However, a nice tool would not only show me the method comment for SophieVersion008, but also any method comments in super classes. Then I get a nice history of what the top class meant to do, maybe why they were subclassed, etc, all in one nice view. |
|
|
In reply to this post by Steven W Riggins
On 9/12/07, Steven W Riggins <[hidden email]> wrote:
These should be compiler warnings, not errors. Not all methods and classes need comments. Personally I'd rather see a code analysis tool (like lint) that gives you these warnings and summaries about how good your code is. Michael. |
|
|
On 12-Sep-07, at 3:07 PM, Michael van der Gulik wrote: > > Personally I'd rather see a code analysis tool (like lint) that > gives you these warnings and summaries about how good your code is. > When I was managing at ParcPlace I had just such a tool. It was called 'tim reviews your code' and boy did I ever give warnings and summaries. tim -- tim Rowledge; [hidden email]; http://www.rowledge.org/tim Hackers have kernel knowledge. |
|
|
On 13/09/2007, tim Rowledge <[hidden email]> wrote:
> > On 12-Sep-07, at 3:07 PM, Michael van der Gulik wrote: > > > > Personally I'd rather see a code analysis tool (like lint) that > > gives you these warnings and summaries about how good your code is. > > > When I was managing at ParcPlace I had just such a tool. > > It was called 'tim reviews your code' and boy did I ever give > warnings and summaries. Nice tool :) I wonder what tool we must invent to completely make our work useless. Tool writes code, adds comments, putting update to MC. And dev just sitting and playing favorite game :) > > tim > -- > tim Rowledge; [hidden email]; http://www.rowledge.org/tim > Hackers have kernel knowledge. > > > > -- Best regards, Igor Stasenko AKA sig. |
|
|
In reply to this post by Blake-5
The trouble with your argumentation is that you assume one only has
"business" with a class if one knows it already. In which case I'd agree that comments are generally unnecessary because you know about it already so what would be the point. However, generally speaking this is only ever true for a single person - he who writes the code in the first place. The second, or third person will not have the intricate knowledge that makes comments unnecessary - I see this every day in our own code, even in areas where I'm pretty familiar with the underlying reality. The comment I quoted from our code base *was* helpful for me because it documented something about the usage that otherwise I would have had to spend time in the tools to reverse engineer its implications. The fraction case is interesting for yet another reason: Fraction (contrary to your contrived precinct example) is a real class in the Squeak core. We can expect that a *lot* of people, regardless of whether their background is mathematics or art, whether professional programmer, retired or in school will look at it. Do you really think that, for all of these audiences, having no comment is better than the comments I provided? Cheers, - Andreas Blake wrote: > On Wed, 12 Sep 2007 10:09:23 -0700, Andreas Raab <[hidden email]> > wrote: > >> Numerator and denominator are no such accessors for sure. First, they >> describe pretty complex objects and just because *you* know what these >> mean doesn't mean everybody else does. Secondly, the denominator has >> even exceptional conditions (like that it can't be zero) which is >> *most definitely* in need of commenting. I'm sorry but your example >> falls far short of the point you're trying to make. > > Disagreed. Unless you want to argue the position that part of the > Fraction class's responsibility is to teach someone who doesn't know > what a fraction is, what a fraction is. (In which case, I still disagree.) > > It's not just =me= who knows what they are, it's anyone who has any > business using the Fraction class. Your class comment for numerator and > denominator say nothing that isn't in the dictionary. > > Let me use a more obscure example: Say I create a voter database for > a registrar and I have a variable for the precinct that the voter is in. > Should I then, as an accessor comment, explain what a precinct is? Its > role in the electoral college? The history of gerrymandering?[1] > > It's not the job of code comments to explain reality, the language > of what being modeled, or common non-code abstractions (like fractions). > Code comments should explain where code diverges from reality, where the > variables used might be misleading, or where accepted abstractions are > changed. For example, SmallInteger and Large*Integer comments usefully > point out their limitations, which have nothing to do with the concept > of Integers. They don't explain WHY, and go into the concept of the > machine word, etc. > > Ultimately, it's all abstraction, which one could argue demands > explanantion of what is being modeled. But at some level, a programmer > says, "Yes, I know this variable 'pineapple' isn't =actually= a > pineapple, but it's convenient to pretend it is." > > If you comment EVERYTHING, you end up devaluing the comments that > are actually meaningful. And so, the one time the programmer is using > "pineapples" to mean "hand grenades" you miss it, because you've grown > accustomed to ignoring the comments, which are mostly noise. And from > what I've seen, code comment posses often end up adding a lot of noise > which is at best useless, and at worst, confusing. > > ===Blake=== > > [1] I have provided that sort of basic education in supporting documents > and occasionally even in class comments, but it shouldn't be mistaken > for any kind of =code= documentation, and is generally a poor substitute > for having actual education. > > |
|
|
In reply to this post by Igor Stasenko
On Wed, 12 Sep 2007 15:36:55 -0700, Igor Stasenko <[hidden email]>
wrote: > On 13/09/2007, tim Rowledge <[hidden email]> wrote: >> >> On 12-Sep-07, at 3:07 PM, Michael van der Gulik wrote: >> > >> > Personally I'd rather see a code analysis tool (like lint) that >> > gives you these warnings and summaries about how good your code is. >> > >> When I was managing at ParcPlace I had just such a tool. >> >> It was called 'tim reviews your code' and boy did I ever give >> warnings and summaries. > > Nice tool :) Are you saying Tim's a tool?<s> |
«
Return to Squeak - Dev
|
1 view|%1 views
| Free forum by Nabble | Edit this page |