On Fri, May 17, 2013 at 6:27 AM, dimitris chloupis <[email protected]> wrote: > I really enjoy smalltalk, every small thing that I discover every day. > > But there is one thing that really annoys me. The bold claim that small > functions do not need comments. > There is of course a level of truth that when a function/methods is well > formated and follows the common logic > rules of readable code a comment should not be needed for what it takes 10 > lines or less of code to explain. > > But then that is also an illusion. > > The problem is that the code never explains the why. And why can be very > important in understanding the code.
You are right that comments should explain the "why" and not the
"what". But not every single tiny little method needs to explain the
"why" of its existence. Do you think hundreds and hundreds of
#initialize methods need to explain themselves with a comment? I
don't.
> Also a big issue I have with smalltalk in general. All this spaggeti mess I
> see unfold before my eyes in every library I see.
> One method calling another method which calls (excuse me, I should have said
> "sends a message") another and before
> you know you forget where you started and where is the end. Its the
> definition of Code Labyrinth. All this hectic browsing
> around could have been avoided so easily with a single comment.
Your frustration about use of the Composed Method pattern is due to a
tool shortage, not a shortage of comments. Above, you're talking
about getting "lost" as you trace through senders and implementors.
When each sender/implementor either opens up a whole pane or, in some
cases, a whole new window, then yes, it's very easy to get "lost" and
forget where what you were doing due to following side-tracks.
That's why I use Squeak's MessageTrace, it handles this better than
anything else in any Smalltalk. It is a "lightweight" way, in terms
of gestures and UI elements, to trace through code without getting
lost. I wish Pharo would consider implementing a tool like this.
> I would like to note here that I am also a big fan of small methods and that
> my question is not related to whether methods
> should be kept small and readable but whether comments are really needed for
> those methods.
Consulting Kent Beck's book, "Smalltalk Best Practice Patterns", page
40, on the "Method Comment" pattern. Kent suggests the percentage of
methods that should need commenting is "between 0 and 1 percent." He
continues about why on page 41:
"Regardless of how well the system as a whole is put together,
the big picture cannot easily be read method by method. There has to
be another way of teaching the reader about the system as a whole."
That's exactly what MessageTrace does. It shows the "big picture" of
what's going on simply by arrowing up and down through the trace and
reading the code.
Comments are a human labor. They take time to write and time to
read/ignore. Therefore, too many comments will actually *detract*
from the quality and producitivity of a system if they're redundant,
ambiguous, or sometimes even wrong, and making the code messy and hard
to read. If, instead, we can design good-enough tools to _present_
the code model in a way that can be easily understood, then we don't
need to labor over writing/reading comments except any more than 1% of
the time.
Cheers,
Chris
<<attachment: MessageTrace.png>>
