Friday 17 April 2009

To document or not to be

The first of the 10 commandments for software developers says:
"Thou shall document thy code"!

And this is unfortunately also the most frequently violated rule! Which also applies to Smalltalk developers!

The Seaside authors have constantly violated this rule!

There is virtually no documentation inside the code or for the classes. This is even worsened by the fact that many class names, method names and instance variable names are simply wrong. They don't do or deliver what their names promise. They are misleading any potential user of the Seaside library and stealing their time!

I think that this cannot be tolerated!

If one wants to build products on Seaside, there must be some good documentation inside the code, which allows a developer to understand quickly what is going on without reading the code.

I think that it is very amateurish and ignorant not to document such a complex class library at all! There is no excuse for it!

I can only assume that it is either or both of these reasons:

The authors planned to sell their experience and advise instead of providing a documentation. I think that this would be fair enough provided that it is openly stated (which it is not).

Alternatively it could be this frequently found ignorance of primarily younger and rather mathematically minded developers who just ignore elder people's experience that it always pays back to invest into proper documentation even for the original developer himself. Many of these mathematical people have simply problems to express their thoughts in clear words.

In my team and my work such an ignorance was never tolerated! And I am not willing to waste my time discussing this unconditionally mandatory requirement of documenting code!

By the way: The original PARC Smalltalk library was and still is a piece of art and the perfect example for well documented and concise code. Unfortunately, the newer VW classes are nowhere near this high standard.

Lucas Renggli was most ignorant when I offered my help to document Seaside. See more in: "On the darker side of Seaside".

I therefore propose a Seaside documentation community to exchange our documentation work. My team and I have already done a lot in this respect and I am offering this to everybody who is willing to contribute to this vital subject.

Of course, I also invite the Seaside authors to collaborate with us in this respect. Just drop me a line and I will come back to you with my proposals.

3 comments:

  1. Hi, I just read your post on the Squeak mailing list and your posts here!

    Good idea! This is really the greatest disadvantage of Seaside!

    You are a bit harsh with your words but essentially you are right. I will contact you by email.

    Regards and good luck

    ReplyDelete
  2. It's useful to be critical.

    But I think many of your things are blown out of proportion.

    You also seem to be unware of important facts:

    (a) Lukas is *not* the lead Seaside dev -- just an advocate, like I am
    (b) everything you've found wrong is either already in the Seaside bug
    tracker, or you can easily put it there, where someone will fix it
    given resources
    (c) the 2.9 release has gone a long ways towards documenting all the classes

    but most importantly:

    (d) telling volunteers that they aren't doing their job in a way that *you*
    find acceptable is about the least effective way to change behavior.
    Seriously.

    And in the long run, this will harm the Seaside community more
    than help it, because people googling for Seaside will see your
    blog.

    What did we do, as a community, to deserve your wrath?

    Here's how you can help:

    (1) report specific things you find to the tracker
    (2) get involved *solving* those bugs by joining the dev team instead
    of yelling at them (or in their general direction)
    (3) stop with the hysterics in your blog - getting third parties agitated
    is harmful, not helpful.

    The real question is that you must ask yourself:

    Do you want Seaside to succeed?
    Or do you just want to point out that Seaside has failed you, without
    actually having tried to help Seaside?

    Choose one. You can't choose both.

    ReplyDelete
  3. Hello Randal!

    Thank you for your critics. You got my intentions wrong. See my comments below:

    >(a) Lukas is *not* the lead Seaside dev -- just an advocate, like I am<
    That is exactly what I wrote in my post. But Cincom in the past was not any better, just much politer. And I did not again want to run into the USA versus Europe problem.

    >(d) telling volunteers that they aren't doing their job in a way that *you* find acceptable is about the least effective way to change behavior.<
    I offered my help, which was rejected in the most arrogant way possible! My examples of bad coding (most to come soon) are not *my opinion* but you can find the same in many Smalltalk books and tutorials etc.

    >And in the long run, this will harm the Seaside community more than help it, because people googling for Seaside will see your blog.<
    It helps most to take such critics seriously rather than keeping them under cover or rejecting them. I am sure many people were already pissed-off in the past by the facts that I mentioned publicly.

    >What did we do, as a community, to deserve your wrath?<
    By no means the community. I want to improve the product to ease our work.

    >(2) get involved *solving* those bugs by joining the dev team instead of yelling at them<
    Well, this is another public way of offering my help, which was rejected. Yelling often helps to be better heard!

    >Do you want Seaside to succeed?<
    What a question! We have already invested too much!

    >Or do you just want to point out that Seaside has failed you, without actually having tried to help Seaside?<
    I offered my help. It was most rudely rejected! We have invested too much in Seaside!

    But as the posts in the mailing prove, there is this wide-spread Smalltalker arrogance ("we don't need to document, it's Smalltalk and who doesn't understand it is stupid anyway"). I have been around far too long to be naive in these respects. I wish it was different!

    May I propose to continue this discussion here in the public rather than in this "conspirative community" mailing list.

    Best regards
    The Smalltalk Blogger

    ReplyDelete