On 17 May 2013 18:56, Chris Muller <asqueaker@gmail.com> wrote:
On Fri, May 17, 2013 at 6:27 AM, dimitris chloupis <thekilon@yahoo.co.uk> 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.
So, propose it! How I (or other pharo developers) can consider something, which they never heard about? I joined Squeak in 2006, still never heard about it when using Squeak, not saying about pharo.. I actually get used to use browsers with minimal feature set, because over the years, i used many different images with many (non-working/half-broken) things.. so i developed habit to not even try advanced features :)
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."
+1
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.
again, +1 Today, i practicing putting a decent documentation in class comments, describing the "why", "how" and "don't" altogether.
Cheers, Chris
-- Best regards, Igor Stasenko.