A simple: "Provides the ability to...." "Provides support for..." "Enables to ..."
already goes a long way. Phil 2013/5/17 Igor Stasenko <[email protected]> > On 17 May 2013 13:46, stephane ducasse <[email protected]> wrote: > > I agree with you. > > > > Methods should be commented!!!! > > > indeed.. i like reading nice comments.., much less than writing them, > however :) > > nice point that comments must focus on answering "why" but not "how" > > > > > On May 17, 2013, at 1:27 PM, 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. > > 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. > > > > Its those moments you beg for a comment or some documentation. > > > > So my message to this list is to express my discomfort on this and ask > > > > Is it me or is this a really bad code practice afterall ? > > > > I am new to smalltalk so maybe I miss something or maybe things get > easier > > in the future with more experience. > > But something it tells me inside that I will never get used to this , > maybe > > I will learn to tolerate it , but its so far away from > > my way of thinking I dont think it has much chance into integrating in my > > brain. > > > > The thing is that I am quite the opposite , I am a comment and > documentation > > freak. You may think I do it just to be > > awared the oscar of amazing readable coding but nothing can be further > from > > the truth. I may be coding for 25 years now > > but it was never something serious , I am no pro and certainly not a > serious > > coder. I just like to mess around with code, thats all. > > > > For me its a matter of survivability , if I dont comment or document I > will > > quickly forget why I code these things anyway. > > Its so easy for me to forget and be confused and I find in this case > > smalltalk code is not as forging to coders like me. > > > > So I would like to hear you thoughts on this as much more experience > > smalltalk coders than me. > > > > 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. > > > > > > > > -- > Best regards, > Igor Stasenko. > >
