discovering public repository items?

> Von: Mark D. Roberts [mailto:[hidden email]]
>
> At 09:46 AM 7/20/2006, James Robertson wrote:
> >Hmm.  I spent my time in the mines of C (and other
> languages).  Believe
> >me, comments were no more common there than they are in
> Smalltalk.  Don't
> >mistake the "corporate standard" comment blocks at the top of each
> >function as meaningful comments - they are typically
> copy/pasted, possibly
> >edited, and then never, ever kept up to date.
>
> http://docs.python.org/lib/lib.html
>
> I can't speak as a Python expert, but looking at this it
> seems that every
> module has a comment.
>
>
> >At 08:41 PM 7/19/2006, you wrote:
> >>Jaroslaw,
> >>
> >>At 06:59 AM 7/20/2006, Jaroslaw Podgajny wrote:
> >>>The question is what can be done to make it more natural
> to put comments
> >>>in all beneficial places. If there was a way to make
> people see the
> >>>benefits of writing the comments straightaway or somehow
> make it part of
> >>>the development cycle things could look different.
> >>>I have a similar feel that adding more ways of commenting
> code will not
> >>>work. Forcing constrains around it won't work either. It has to be
> >>>integrated into environment and "make sense to write them"
> for the idea
> >>>to pick up.
> >>
> >>After looking at this problem for several years, my
> conclusion is that
> >>there is an underlying cultural dimension that is separate
> from the tools
> >>issue, and this now seems to me more decisive. For whatever reason,
> >>Smalltalkers just tend not to write comments. In other programming
> >>communities, comments are considered part of the
> development process. In
> >>ours, they are not. Smalltalkers have various excuses for
> why comments
> >>are not necessary, which eventually conflict with the needs
> of somebody
> >>trying to learn Smalltalk or re-use some existing code. In
> the larger
> >>scheme of things, the lack of comments serves to isolate us
> from the rest
> >>of the world.
> >>
> >>This thread started because somebody was looking in the public
> >>repository, found no comments for the code components
> published there,
> >>and then (very charitably) wondered if the comments were to
> be found
> >>somewhere else. The answer was "no" and this is where the
> rubber hits the
> >>road. Then, we started talking about ways to improve the situation.
> >>
> >>While I agree that we can and should improve the tools, the
> pay-off is
> >>likely to be small. As Jim pointed out, if people won't use
> the existing
> >>mechanisms they likely won't suddenly start making
> extensive use of any
> >>new tool options. We can get some improvement, we need to
> improve the
> >>tools, we need to be realistic about the outcome.
> >>
> >>So, we might also consider "social" solutions to this
> problem. Right now,
> >>nobody is in charge of the public store and the burden
> falls upon each
> >>user to decide what each component does, what works, what
> doesn't, what's
> >>released, what's obsolete, etc. There are no conventions,
> no rules. If
> >>somebody were in charge of the repository and they could act as an
> >>editor, marking some things obsolete, nagging developers
> about comments,
> >>etc., it would help to improve the new-user experience. The
> tools also
> >>need to be improved, Store is deficient in this regard, but
> if we really
> >>care about making the public repository accessible to new
> developers,
> >>then I think we need to do both.
> >>
> >>Imagine that we were all journalists working for a
> newspaper called "The
> >>Public Store Times". We write articles, and through the
> miracle of modern
> >>technology, we publish them ourselves. Yet, we have no
> editor in charge
> >>of our newspaper, and we have no editorial standards. Each
> journalist has
> >>his/her own idea about what at article looks like. Sometimes,
> >>occasionally, new people read our newspaper and say "Your
> newspaper is
> >>kind of tedious to read -- how about including a little
> summary before
> >>each article?". At this point, we might discuss editorial
> standards --
> >>"What should an article look like? How should it be
> organized? Should it
> >>have a one-line summary? Should we refuse to release it
> until it does?
> >>Etc." We might discuss an editorial function, i.e., "Should
> we try to get
> >>an editor in charge of this?". Finally, we might discuss
> tools, i.e.,
> >>"How can we improve our tools so that it is easier to write
> good articles?".
> >>
> >>This last discussion about tools is what we always have,
> but clearly this
> >>is not enough. We could improve our tools 200% but some
> journalists still
> >>won't use them. In lieu of new policies and somebody to
> enforce them, or
> >>in lieu of a collective decision to suddenly change the way
> we write
> >>articles, the quality of our newspaper probably won't improve much.
> >>
> >>This is a half-hearted analogy, but the point is clear
> enough. Since we
> >>do not collectively think it is important to communicate
> with new users,
> >>e.g. by making our repository legible to them, we haven't really
> >>discussed editorial standards or an editorial function
> (somebody "in charge").
> >>
> >>If we decide that we care about making the public store
> more legible to
> >>new developers, we might do the following:
> >>
> >>         -- Institute a policy that any code marked as
> "released" must
> >> have adequate package/bundle comments
> >>         -- Decide on a simple definition of an "adequate" comment
> >>         -- Put an administrator in charge of the
> repository who can
> >> change blessings on components, e.g., demoting anything
> that is blessed
> >> as "released" which lacks comments
> >>         -- Fix the Published Items tool to include a
> "blessing filter"
> >> so that by default in VisualWorks NC, it only shows
> released components.
> >> The filter can be twiddled easily, of course.
> >>         -- Improve the IDE tools for adding comments,
> perhaps along the
> >> lines of SmalltalkDoc
> >>         -- Add a web interface for displaying the contents of the
> >> repository, again, along the lines of SmalltalkDoc
> >>
> >>If we did all of these things, it would dramatically
> improve the noob
> >>user-experience with Store. It would make it easier for new
> developers to
> >>join us, i.e., to grow our community.
> >>
> >>>The problem is similar to the issue of maintainability of
> a help system
> >>>- it is not a challenge to create one. How to make it not
> become patchy
> >>>or deteriorates over time is the big deal.
> >>>
> >>>We have a demand for a good help system but not much
> thoughts went into
> >>>it yet Some wild ideas were going in the direction of integrated
> >>>wiki/blog things... Any ideas welcome.
> >>
> >>This point is tangential to the thread, but by chance I
> have done some
> >>work on the VisualWorks Help System and my experience has
> been similar to
> >>yours. The problems are in authoring content and
> maintaining the system
> >>and the content. The VW Help system was a prototype, there
> have been no
> >>resources within Cincom to improve it since, and so it has
> deteriorated
> >>into its current state of decrepitude. Since VisualWorks
> lacked basic UI
> >>features like a hypertext widget, we had to build the VW
> Help browser
> >>using a third-party package from Arbor. This package came with no
> >>documentation, inadequate comments (sound familiar?) and it is now
> >>unmaintainable junk. We want to throw it out but, five years later,
> >>VisualWorks still doesn't have any support for hypertext.
> >>
> >> From here, there are roughly two directions ahead. One is
> that we build
> >> hypertext support into VisualWorks and write a new Help
> Browser. The
> >> other is that we punt completely on the idea of integrated
> Help, admit
> >> to ourselves that VisualWorks isn't up to the job of
> building a Help
> >> Browser, and just use an external web browser. The problem
> with the
> >> latter direction is that we lose the ability to click on
> something in
> >> the Help browser and, for example, open a Workspace or
> load a parcel
> >> into VisualWorks. We lose the ability to search the
> content. Also, and
> >> more significantly, all modern IDEs are now moving towards
> integrated
> >> Help/Documentation. Eclipse, for example, has this. The
> facility for
> >> help/documentation/tutorials in Eclipse is now years ahead of
> >> VisualWorks and the gap is only going to grow wider. This
> translates
> >> into a direct impact on the noob experience, and IMHO
> Eclipse now offers
> >> a superior noob experience. We can argue all we want about the
> >> weaknesses of the underlying language, we can argue all we
> want about
> >> the design of the Eclipse IDE, we can be the Sony Beta to
> Eclipse's VHS,
> >> but Eclipse offers a smoother noob experience.
> >>
> >>The other direction would be to build a new Help Browser
> and push for
> >>greater integration of tools/help/doc inside VisualWorks.
> This means we
> >>need to solve the long-standing problem of hypertext.
> Fortunately, the
> >>situation has changed since we built the prototype Help
> Browser. There is
> >>now a real XML display subsystem called WithStyle. It also
> includes an
> >>XML editor. It would not be difficult to build a new Help
> System using
> >>WithStyle. In fact, I made a small prototype to see how it
> would work. It
> >>is not difficult to read the existing Help content and
> translate it into
> >>structured XML, I have tried that too. The difficulty is getting
> >>WithStyle more properly integrated into VisualWorks, and
> finding the
> >>cycles to do all the editorial work to update the content
> and get it into
> >>order. I can't do that now.
> >>
> >>If you are interested in talking about this second
> direction, feel free
> >>to e-mail me directly.
> >>
> >>Cheers,
> >>
> >>M. Roberts
> >
> ><Talk Small and Carry a Big Class Library>
> >James Robertson, Product Manager, Cincom Smalltalk
> >http://www.cincomsmalltalk.com/blog/blogView
> >
>
>
>