Back to the issue... (was RE: Squeak coding style...)

Maarten Maartensz maartens at xs4all.nl
Wed Mar 3 20:56:48 UTC 2004


Hello everybody,

Göran Krampe wrote:

>Hi all!

>Julian Fitzell <julian at beta4.com> wrote:
>> goran.krampe at 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

And since he asks explicitly, I feel I should answer (if no one else except Tim
Rowledge and me agree...)

I am no great Squeak-code-slinger yet, and one reason is that Squeak could do
with better comments. Squeak is a great programming environment and a great
programming language, but it so far has not been well documented. Part of the
reason is the speed with which it is being developed; part of the reason is open
source cooperation; part of the reason is that many people with many outlooks
and different educations and presuppositions cooperate; and part of the reason
is old habits and styles, including writing code and 'forgetting' to comment it
if it works - as if people new to Squeak should have to invent all wheels
allover again, although indeed with the help of a working system.

More to the direct point:  I am a proponent of literate programming. What I
did program most in is Prolog, in which the same line is peddled ('good code is
self-explanatory'). Well, my own experience (some 10 years) is that also with my
own code my own comments are generally useful, especially after a while. Also,
they are easier to read than code, especially lots of code.

After all, code is so simple-minded in structure as to be parsable by a mere
inanimate machine. And at least my human mind, although it loves mathematics,
just likes to have things explained on many levels, including good English, and
at least my human mind is better at comprehending good English than
comprehending good mathematics or good code.

Next,  in Squeak it should be possible, I think, to get a good idea of what an
object and its methods are  supposed to do by just reading the documentation
(using the button for it in the Browser). And this good idea needs to be
rendered in good and clear English (if English is the language you comment code
in). Indeed, somebody who is a good Squeak-programmer should get good ideas how
the code could or should look given merely the English documentation.

Having good documentation is an act of politeness and human kindness to all
future users of the code, which includes you-who-originally-wrote-it. It is what
enables others to rapidly understand at least the main purpose and outline of
the code, and the intentions of its maker.

Moreover: Good comments of what the code is supposed and intended to do is very
useful when debugging. And what it is supposed and intended to do code
just cannot convey explicitly. It NEEDS a comment - for the code itself may be
bugged even if it runs and passes tests. And code doesn't think, doesn't know,
and doesn't have the intentions of its writer - it merely is a rendering of what
he intended and thought might realize his intentions programmatically.

This is also related to the reason why even most books of pure mathematics are
mostly text and not mathematics. One explains in English what it is one wants to
do and why it would be nice or interesting, and also where and what the fine
mathematical points and clever bits are, and shows in mathematics that and
how it can be done. It's the same in programming - or it should be, and could
be, with better comments and a style of literate programming which could be
achieved in Squeak.

I have said, your honours, and am sorry if I bored you.

Regards,

Maarten.
------------------------------------------
Maarten Maartensz. Homepage:
http://www.xs4all.nl/~maartens/
------------------------------------------





More information about the Squeak-dev mailing list