On 17 May 2013 18:56, Chris Muller <[email protected]> wrote: > 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. > 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.
