A simple: "Provides the ability to...." "Provides support for..." "Enables to ..." already goes a long way. Phil 2013/5/17 Igor Stasenko <siguctua@gmail.com>
On 17 May 2013 13:46, stephane ducasse <stephane.ducasse@free.fr> 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 <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. 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.