6 ms·

IMO, if I feel the need to add comments to explain code blocks like this: > // Add a horizontal scroll bar > hScrollBar = new JScrollBar(scrollBar, HOR

IMO, if I feel the need to add comments to explain code blocks like this: > // Add a horizontal scroll bar > hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); > add(hScrollBar, BorderLayout.SOUTH); It's a sign I should be writing code that reads more like: > addHorizontalScrollBar()

cdubzzz 5y ago
Do you then document the new function, though?
- pixel_tracing 5y ago
  I think the function name is pretty self documenting, I would go a step further and make a function named addScrollBars() clear on its intention here
  - cdubzzz 5y ago
    Sure. Agreed. But I still docblock every function I write so this wouldn’t change much with respect to usefulness of the documentation.
- lkrubner 5y ago
  You've heard the XTreme slogan "Where you would write a comment, we would write a method"?
nitrogen 5y ago
If you're building a UI frame, like in this Swing example, I think it's reasonable to keep the code in a single method and separate it into functional blocks with comments. But the variable names and comments should still include a bit more of the why. Example: // Build the data table view ... // Add horizontal scroll bar to the data table view // This is needed if the table has more than N columns tableHScroll = // etc // Build the data navigation sidebar ... As an aside, I wish web UI programming was more like a declarative form of Swing (that is, a widget- and layout-oriented tree), rather than the current mess of React and a text-/document-oriented tree.
- tharkun__ 5y ago
  Think about this. You intentionally left out the very verbose parts of actually doing those things for us to see what your UI looks like on an abstract level here on HN. You basically only gave us the comments and left out the 49 lines of actual code needed in between for each ... With methods extracted you could do the exact same but on actual code and help your future self that forgot all about this class or some other poor developer that has never seen this UI or the code before.
UglyToad 5y ago
I think my problem with this approach and why I lean to favouring the more obvious and verbose comment is, if I'm reading the code it's probably because something is broken (or I need to change something in the area). With the function I think, "is it and if it is what else does it change?". Is that function definition actually doing what it says it is? So now I have to add another stack frame to my mental model, go to definition on the function, confirm that is indeed what it claims to do, pop the frame and resume my reading of the parent method. With the comment I get the statement of intent and can see if the code matches inline. Now it's fair to say a good code review culture (and immutability) might create code where there's more room to trust named functions, but I've not seen it yet.
- tharkun__ 5y ago
  I don't really get why your mental model is bothered more by the function/stack frame than the comment. Whether I read a function name or comment personally that does pre occupy my mind and sets the mental frame for what comes next. If the comment or function name say doX() or //this does X then I expect it to do that but need to be on the lookout for whether it actually does that. With a function though I can easily step out if this part turns out not to be interesting, I can easily step over it next round if debugging, I don't need to keep track of where //this does X ends etc. Of course none of these help if the previous author was really bad at what they were trying to communicate. They can both implement doY() in a function called doX() and have //do Y code run in with //do X for example by interleaving statements for both. If we assume we'll intentioned authors for both though, I would tend to see more pros for structuring code with functions than via comments.
  - nerdponx 5y ago
    Stepping in and out is an extra step, mentally and physically. It's increased burden on my working memory, which is usually already quite full keeping track of other aspects of the task at hand. Also it imposes more burden on the author, and possibly could lead to developing the wrong abstraction, which we all know is bad.
    - 5y ago
mumblemumble 5y ago
Meh. If you're only doing it once, then I'd argue that the main practical difference between // Add a horizontal scroll bar hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); and (assuming scrollBar is not a local variable) void addHorizontalScrollBar() { hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); } ... addHorizontalScrollBar(); is whether you want to do it in 3 lines or 5. (edit: disclaimer -- Snark aside, I should say that I personally tend toward the latter option. But I am absolutely not prepared to try and convince anyone that it is, in any objective sense, better. It's just an aesthetic preference. Maybe even a nervous habit.)
- tharkun__ 5y ago
  I think this is a question of level of abstraction. I would argue that that this more readable as for what is going on: addHorizontalScrollbar() ; addVerticalScrollbar(); addHeader(); addDayColums(); addFooter(); If all I need to know is how the page is structured and set up on a high level, then this is awesome (actually I'm not convinced it needs the scroll bar stuff on this level but this was what I could come up with to stay in the example :) ) I don't need to read comments for what's what and then manually skip over ever so many lines of actual code that did all these things. I can decide that what I really wanted to take a closer look at was what the header bar looks like. Some of this depends on whether I'm using an IDE or not. In an IDE I can just Ctrl click myself through. Then again I doubt anyone these days is using _just_ vi to code something complex enough to want multiple files. I used vi configured as an IDE way back but I do admit that's been like 15 years. Dunno what that looks like today. Nowadays I'm a JetBrains user, mainly in Java and Java/TypeScript and very little Python.
  - js8 5y ago
    This might be more readable if setting up those things doesn't involve a set of common variables (say a GUI style in this example) that can affect them. If it does, then you have to pass them around (into these functions) and it makes more difficult to figure out, if one of these variables changes, what all is affected by it (you have to look up all those methods). In short, I don't think adding depth to a hierarchy of function composition is always an answer. Flatter hierarchies can be easier to understand too.
flukus 5y ago
This sounds perfectly reasonable in isolated examples, but I find maintaining large applications written in this style to be a nightmare. Once you get to non-trivial examples you'll have a lot of variable being passed around (what are we adding the scrollbar too) and stepping through a million little functions to see which components are interacting and how. The first example might need a comment, but everything I need to know is right there in one place and not distributed across the codebase.

cdubzzz 5y ago

Do you then document the new function, though?

pixel_tracing 5y ago
I think the function name is pretty self documenting, I would go a step further and make a function named addScrollBars() clear on its intention here
- cdubzzz 5y ago
  Sure. Agreed. But I still docblock every function I write so this wouldn’t change much with respect to usefulness of the documentation.
lkrubner 5y ago
You've heard the XTreme slogan "Where you would write a comment, we would write a method"?

nitrogen 5y ago

If you're building a UI frame, like in this Swing example, I think it's reasonable to keep the code in a single method and separate it into functional blocks with comments. But the variable names and comments should still include a bit more of the why. Example: // Build the data table view ... // Add horizontal scroll bar to the data table view // This is needed if the table has more than N columns tableHScroll = // etc // Build the data navigation sidebar ... As an aside, I wish web UI programming was more like a declarative form of Swing (that is, a widget- and layout-oriented tree), rather than the current mess of React and a text-/document-oriented tree.

tharkun__ 5y ago
Think about this. You intentionally left out the very verbose parts of actually doing those things for us to see what your UI looks like on an abstract level here on HN. You basically only gave us the comments and left out the 49 lines of actual code needed in between for each ... With methods extracted you could do the exact same but on actual code and help your future self that forgot all about this class or some other poor developer that has never seen this UI or the code before.

UglyToad 5y ago

I think my problem with this approach and why I lean to favouring the more obvious and verbose comment is, if I'm reading the code it's probably because something is broken (or I need to change something in the area). With the function I think, "is it and if it is what else does it change?". Is that function definition actually doing what it says it is? So now I have to add another stack frame to my mental model, go to definition on the function, confirm that is indeed what it claims to do, pop the frame and resume my reading of the parent method. With the comment I get the statement of intent and can see if the code matches inline. Now it's fair to say a good code review culture (and immutability) might create code where there's more room to trust named functions, but I've not seen it yet.

tharkun__ 5y ago
I don't really get why your mental model is bothered more by the function/stack frame than the comment. Whether I read a function name or comment personally that does pre occupy my mind and sets the mental frame for what comes next. If the comment or function name say doX() or //this does X then I expect it to do that but need to be on the lookout for whether it actually does that. With a function though I can easily step out if this part turns out not to be interesting, I can easily step over it next round if debugging, I don't need to keep track of where //this does X ends etc. Of course none of these help if the previous author was really bad at what they were trying to communicate. They can both implement doY() in a function called doX() and have //do Y code run in with //do X for example by interleaving statements for both. If we assume we'll intentioned authors for both though, I would tend to see more pros for structuring code with functions than via comments.
- nerdponx 5y ago
  Stepping in and out is an extra step, mentally and physically. It's increased burden on my working memory, which is usually already quite full keeping track of other aspects of the task at hand. Also it imposes more burden on the author, and possibly could lead to developing the wrong abstraction, which we all know is bad.
  - 5y ago

mumblemumble 5y ago

Meh. If you're only doing it once, then I'd argue that the main practical difference between // Add a horizontal scroll bar hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); and (assuming scrollBar is not a local variable) void addHorizontalScrollBar() { hScrollBar = new JScrollBar(scrollBar, HORIZONTAL); add(hScrollBar, BorderLayout.SOUTH); } ... addHorizontalScrollBar(); is whether you want to do it in 3 lines or 5. (edit: disclaimer -- Snark aside, I should say that I personally tend toward the latter option. But I am absolutely not prepared to try and convince anyone that it is, in any objective sense, better. It's just an aesthetic preference. Maybe even a nervous habit.)

tharkun__ 5y ago
I think this is a question of level of abstraction. I would argue that that this more readable as for what is going on: addHorizontalScrollbar() ; addVerticalScrollbar(); addHeader(); addDayColums(); addFooter(); If all I need to know is how the page is structured and set up on a high level, then this is awesome (actually I'm not convinced it needs the scroll bar stuff on this level but this was what I could come up with to stay in the example :) ) I don't need to read comments for what's what and then manually skip over ever so many lines of actual code that did all these things. I can decide that what I really wanted to take a closer look at was what the header bar looks like. Some of this depends on whether I'm using an IDE or not. In an IDE I can just Ctrl click myself through. Then again I doubt anyone these days is using _just_ vi to code something complex enough to want multiple files. I used vi configured as an IDE way back but I do admit that's been like 15 years. Dunno what that looks like today. Nowadays I'm a JetBrains user, mainly in Java and Java/TypeScript and very little Python.
- js8 5y ago
  This might be more readable if setting up those things doesn't involve a set of common variables (say a GUI style in this example) that can affect them. If it does, then you have to pass them around (into these functions) and it makes more difficult to figure out, if one of these variables changes, what all is affected by it (you have to look up all those methods). In short, I don't think adding depth to a hierarchy of function composition is always an answer. Flatter hierarchies can be easier to understand too.

flukus 5y ago

This sounds perfectly reasonable in isolated examples, but I find maintaining large applications written in this style to be a nightmare. Once you get to non-trivial examples you'll have a lot of variable being passed around (what are we adding the scrollbar too) and stepping through a million little functions to see which components are interacting and how. The first example might need a comment, but everything I need to know is right there in one place and not distributed across the codebase.