Small Methods dont need comments , true or myth ?
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 questionis not related to whether methods should be kept small and readable but whether comments are really needed for those methods.
I agree with you. Methods should be commented!!!! 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.
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.
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.
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.
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
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.
+1
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.
Can you explain it? This is the screenshot? The top line the sender for ensureSecondaryLinkConfigured then see its senders? Its self sends? Because I want (and I was thinking about that too for long time) something like that.
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.
Hi,
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.
Can you explain it? This is the screenshot? The top line the sender for ensureSecondaryLinkConfigured then see its senders? Its self sends? Because I want (and I was thinking about that too for long time) something like that.
Yes that is a screenshot. MessageTrace is just a subclass of the classic MessageSet which, when the user highlights a chunk of code in the bottom pane and presses i(m)plementors, rather than opening a new window or pane, the implementors are listed in the top-half of the same browser, indented below the currently selected message. Likewise, when the user selects (s)enders on a message in the upper pane, it outdents those senders above the selected message. Multiple paths of flow can be built. Since it does not do type-inference, heavily overloaded selectors will cause many extra senders/implementors to be put into the browser -- so to handle this the UI merely allows the user to easily trim unwanted messages with a couple of simple gestures (swipe select + Command-d). The result is a single window that encapsulates the method flow of a single piece of functionality (e.g., a "Trace") that the user can comprehend because of the way it is presented. Try it out in Squeak is the best way to appreciate it. The code for it is not complicated I'm sure it could be adapted into Pharo..
Yes that is a screenshot. MessageTrace is just a subclass of the classic MessageSet which, when the user highlights a chunk of code in the bottom pane and presses i(m)plementors, rather than opening a new window or pane, the implementors are listed in the top-half of the same browser, indented below the currently selected message.
Likewise, when the user selects (s)enders on a message in the upper pane, it outdents those senders above the selected message. Multiple paths of flow can be built.
Since it does not do type-inference, heavily overloaded selectors will cause many extra senders/implementors to be put into the browser -- so to handle this the UI merely allows the user to easily trim unwanted messages with a couple of simple gestures (swipe select + Command-d).
The result is a single window that encapsulates the method flow of a single piece of functionality (e.g., a "Trace") that the user can comprehend because of the way it is presented.
Try it out in Squeak is the best way to appreciate it. The code for it is not complicated I'm sure it could be adapted into Pharo..
Thanks for the explanation. I will try it in squeak because when I thought about that browser I was concerned with the senders/multiple implementors display. Stef
I happen to own that book so I did take a look at it last night and then another look and then another and was still not convinced. You see I am a practical person , and even though I am nowhere near to being a pro code I have my fair share of libraries and their design. The thing that I learned is what others may consider a good design , simple and easy to understand for me it becomes quite a problem and quite the opposite. Kent Becks makes the big assumption that people's brain work the same way. Just because he sees his methods and can immediately understand what they do because of a good design that does not apply for everyone. About having a specialized tool does not solve the problem its just makes it more tolerable. Its just like telling you that I wont remove the bugs from my programm instead I will give you a debugger so you can do it easier. It makes the big assumption that the developer really cares how the library works. He does not, only thing he wants is to use the library and in many cases not even the entire library just portions of it. What happens when he does not know what portions exactly to use to get the result he wants does he go through tracing every singe method ? Is this really simple coding ? For me small methods , EVERY method needs a comment , not because its that hard to read a few lines of code but because its plain simpler and faster. And the whole argument that comments are extra labor , yes its true , but one thing I have learned is coding is 99% reading and 1% about writting to use Kent Becks numbers. Unless you use libraries you already know where obviously you fall outside the scope of this discussion. I never saw documentation or writting comments as the time wasting that many coders see it. I find bug hunting way more troublesome. At least you confirmed my suspicion that this theory is based on the over confidence of code design. There is some truth into it of course , but its too unreliable at least for me. Thank you for taking the time to explain things to this detail I really appreciate it. -- View this message in context: http://forum.world.st/Pharo-dev-Small-Methods-dont-need-comments-true-or-myt... Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
kilon wrote
EVERY method needs a comment , not because its that hard to read a few lines of code but because its plain simpler and faster.
-100. Prime example: AbstractBindings>>#initialize "Initialization code for AbstractHolder" That comment is totally redundant for everyone but novices (and maybe even for them). It's actually worse than that: a) I have to read it to find out it's a totally useless comment b) As you can see, it's already rotted. The class is called AbstractBindings, but the comment thinks it's AbstractHolder So, I agree that there may be a "why" in many cases that would be great to capture in a comment, it does not apply to *all* cases. ----- Cheers, Sean -- View this message in context: http://forum.world.st/Pharo-dev-Small-Methods-dont-need-comments-true-or-myt... Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
well i was thinking more like methods that do something ... but as i said, if the method is that obvious I am ok with not having it a comment. I would add a comment though for the sake of automatic documentation. Its a python habbit. even empty methods do get whats called as python doc strings , very similar to smalltalk its a string that can be used for generating later on hmtl documentation which makes things obviously a lot easier. And i think thats also another big plus for commenting even empty methods. I have no idea though if pharo has a documentation generation library from method comments. I assume it has . -- View this message in context: http://forum.world.st/Pharo-dev-Small-Methods-dont-need-comments-true-or-myt... Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
participants (7)
-
Chris Muller -
dimitris chloupis -
Igor Stasenko -
kilon
-
phil＠highoctane.be -
Sean P. DeNigris -
stephane ducasse