logoalt Hacker News

klibertpyesterday at 4:50 PM1 replyview on HN

Honestly, as much as I love Smalltalk, I see this post as an illustration of all that's wrong in that community. Instead of documenting the original solution well, making a cheat sheet for it, or gathering examples (which you otherwise need to "hunt" for, according to the author) in one place, we're given another solution on top of the original inscrutable one. That new solution is still undocumented; in the post, there's no explanation of how it was written and how it works; instead, we get another handful of examples.

GToolkit has Lepiter, and Smalltalks in general have comments on classes that can be used to write long-form docs. Yet, the majority of Smalltalkers apparently believe that all that is not needed, and that searching for examples in the codebase gives you all the information you need. It may be true - not in all cases, but some of them - but the efficiency of that process is incredibly low. And that's even if the examples are there - mostly in test code. It's not unusual to find large areas of code that are entirely untested, though, in which case something that could be done in 15 minutes if you were provided with a solid README can take days to figure out.

Yeah, I know: the IDE, the Smalltalk environment, IS very valuable and it DOES give you superpowers. That doesn't fully offset the issue of notorious lack of documentation, though, and in effect, you're still less productive than you could be with Python. GToolkit's Lepiter is a step in the right direction, but even in GT, class comments and method docstrings are sparse. GToolkit-like environment coupled with Emacs Lisp self-documenting docstrings culture would be ideal, but somehow it just won't happen.


Replies

travisgriggsyesterday at 5:22 PM

Interesting. This has not been my experience. I have not regularly worked in Smalltalk for 12+ years, other than the occasional download and show some young programmer how cool the "petri dish of objects" was/is.

For the last many years, I've been working in C, Swift, Kotlin, Python, and Elixir. In no case, have I felt that there was a step difference between the communities. I'm doing a lot of Elixir right now, which supposedly has "the docs are great". And yet, I often can't find the answer I need to figure something out. Sure there's some inscrutible parts of Smalltalk code bases, but my point is, journeying aboard in these other lands (I do quite a bit of Python too), hasn't made me feel like "oh wow, here's the documentation I could never find." Your mileage obviously varies, I respect that. Just wasn't my experience.