5 ms·

The overall advice here (add comments to your code to delineate different 'sections" of a file) is ultimately a bad hack to deal with the fact that your codebas

The overall advice here (add comments to your code to delineate different 'sections" of a file) is ultimately a bad hack to deal with the fact that your codebase is not structured well into function / modules / classes with a single responsibility and the right level of composition. Refactor your codebase to put the related code together, and then this "problem" will disappear and your code will be much easier to change in the future

leghifla 3y ago
"Refactor your codebase to put the related code together" Of course it is a goal, but not always possible. You sometimes have two (or more) conflicting "relations" in the codebase. E.g.: you are dealing with taxes in various countries. Do you group by country or by kind of taxes (on sales, profits, earnings, energy, real estate...) ? The right answer really depends on how your team is organized and how you are making changes.
- froggit 3y ago
  > E.g.: you are dealing with taxes in various countries. Do you group by country or by kind of taxes (on sales, profits, earnings, energy, real estate...) ? Seems like you would be dealing with one of 2 reasonably well defined problems in this case. How to group would follow logically. It's either: 1) "If i will be dealing with one specific type of tax at a time and how it is applied in different countries. (i.e. What are the sales taxes in UK, France, and Germany? )" Group by tax. OR 2) "If i will be looking at one country at a time and their assorted taxes. (i.e. What are the taxes in the UK for income, sales and value added?)" Group by country. Else "i have failed to properly define the problem." that's gonna be the problem.
  - Bjartr 3y ago
    How about when supporting both use cases? A multinational company might need the former for people making decisions across the whole company, and a country specific department doesn't need anything but what's relevant to that country. You could make two tools, but now you're duplicating implementation. Factor out a shared library/service/modularization-approach-de-jour? Good idea, but we're back to the question of how to structure things. You don't always get to enforce that "OR"
jbenoit 3y ago
1. The author links to this file as an example: https://github.com/Semantic-Org/Semantic-UI/blob/49b9cbf47c172c65dc265d213c609ad5e651a6a9/src/definitions/elements/button.less https://github.com/Semantic-Org/Semantic-UI/blob/49b9cbf47c1... . How would you structure it better than it currently is without using sections? 2. So you have a class that has a bunch of getters and setters. Let's just assume that "generate them automatically" is not an option. You want to make it really easy to see the part of the class which is getters, and the part of the class which is setters, and then skim past that. How do you do it? 3. So you have a file that defines 3 data structures. Each data structure has a definition, a bunch of functions for parsing it, and a bunch of functions for serializing it. The author suggests that you split the file into 3 sections for the types, with subsections each for the definition, parsing, and serializing. How would you do it? Let's say the language is Rust or Typescript.
- chrismorgan 3y ago
  At least some of the sectioning in that file would probably be better handled by leaning into the language more, doing things like nesting selectors.
- jaggederest 3y ago
  > 1. The author links to this file as an example: https://github.com/Semantic-Org/Semantic-UI/blob/49b9cbf47c172c65dc265d213c609ad5e651a6a9/src/definitions/elements/button.less https://github.com/Semantic-Org/Semantic-UI/blob/49b9cbf47c1... . How would you structure it better than it currently is without using sections? Dear God it's a 3300 line file. Any way but one long 3300 line file is a significant improvement. I'm being hyperbolic but seriously, instead of button.less it should be deduplicated (less can be much less verbose, pun intended) and be a button directory with several subcomponents in it, like each top level heading. Less is a serious language that you should use the semantic features to organize your code instead of just comments. > So you have a class that has a bunch of getters and setters. Let's just assume that "generate them automatically" is not an option. You want to make it really easy to see the part of the class which is getters, and the part of the class which is setters, and then skim past that. How do you do it? You put it into a getters file and import it into the parent class. Almost every language has features for this. Or you put each attribute into its own file, if any of the getters and setters has smarter logic than just x = parameters[x]. Ideally you build classes that don't have so many attributes that it's difficult to scroll past the getters/setters in the first place - N > 8 is a significant warning sign the code needs to be split unless it's a configuration class or equivalent. > So you have a file that defines 3 data structures. Each data structure has a definition, a bunch of functions for parsing it, and a bunch of functions for serializing it. The author suggests that you split the file into 3 sections for the types, with subsections each for the definition, parsing, and serializing. How would you do it? Let's say the language is Rust or Typescript. It should definitely be in 3 files, possibly 3 folders, in Typescript: (/thing/index.ts, /thing/parsing.ts, /thing/serializing/json.ts) It's so marvelously easy to import things, you should be using modules amply to split up your code. Obviously the 10-lines-of-import-for-3-lines-of-code is too much, but seriously, imports are easy and cheap.
cellularmitosis 3y ago
Ah, yes, my favorite sort of HN reply. The author puts in a lot of effort to precisely articulate an issue which is difficult to articulate, and a commenter just dismisses the entire thing with a vague "You're holding it wrong".
- slingnow 3y ago
  Sometimes, you really are just holding it wrong. Should the OP have written a manuscript to make you feel better? In your mind, should a long, drawn out article only be refuted by something of similar length?
  - ziddoap 3y ago
    >Should the OP have written a manuscript to make you feel better? In your mind, should a long, drawn out article only be refuted by something of similar length? It's not about "feeling better"? It's that the comment is very dismissive and sums up to "just refactor". Advice of "just refactor" (or "just do x") is lazy and ignores all context.
  - Bjartr 3y ago
    > Should the OP have written a manuscript to make you feel better? Nope > only be refuted by something of similar length? No, but if you don't address the points that have been made, you're not refuting. The comment says "refactor your codebase to put the related code together", but the article already addresses some downsides to this approach. Does the commenter believe that those downsides are more avoidable than the article states? Or maybe they believe the downsides are dwarfed by the upsides? Or maybe something else. We don't know, so we can't evaluate the position effectively.
  - rustyminnow 3y ago
    That would make me feel better. Without actionable advice, OP is just just grumbling. It's not helpful. > Refactor your codebase to put the related code together, and then this "problem" will disappear But how do I do that exactly? What does this even mean? I could literally put the whole codebase into one file since it is all related somehow or another.
tikhonj 3y ago
The problem is that real-world domains—or even just relatively complex software domains—do not decompose perfectly into 100% self-contained units. It's not even a limitation of any given programming language (although those limitations matter too!); we can't even have a purely conceptual ontology where everything neatly fits into exactly one slot in a neat hierarchy. That's just not how, well, anything works. It's definitely worth trying to have your code neatly organized in a way that maps to some clean conceptual model, but doing that well is going to require using every tool at your disposal—which includes ways of grouping code that don't need the sort of crisp definition and conceptual coherence of an in-language abstraction. Sections and sub-sections seem like a reasonable way to do that with our modern, painfully limited tools. If we weren't limited by needing everything to live in plain text, I'd also reach for something like a system of tags.
inChargeOfIT 3y ago
This is not always possible and a little short-sighted, especially when you are on a large, complex, established project with many contributors, where "just refactor 1.5 million lines of code, spanning 1500 files that have evolved over a 10 year period" is just something not open for debate. In those cases, and in the cases where a single large file just makes more sense or is unavoidable (IaC/build scripts, shell/sql/migration scripts, config files, etc.), the author's methods are absolutely valuable.
- nightpool 3y ago
  Try working on open source Minecraft projects. You will make these types of refactors monthly. The Bukkit/Spigot API has a 13 year pedigree, 10s of thousands of developers building against it, easily encompasses 1M+ lines of code across the whole codebase and needs to remain nimble in the face of unpredictable upstream changes. Watching the work some of these developers are able to pull off will definitely give you a healthy appreciation of what sorts of refactors are possible when you commit to them. > or is unavoidable (IaC/build scripts, shell/sql/migration scripts, config files, etc. This is a failure of the tooling in question. We shouldn't accept shoddily built tooling as an acceptable justification for unreadable codebases. Obviously, there are tradeoffs and sometimes you just need to get the tool out the door, but when a particular tool (like a professional IaC project) becomes some people's primary programming languages, then treating those languages like second class citizens who "unavoidably" are going to just be awful to work with is just limiting the growth of the tool as a whole. Terraform modules are a great example of this—all that ceremony and hassle just for what is effectively a single function call! If Terraform had single-file modules and a better import system than "relative file paths", I'd expect we'd see a lot more Terraform code bases with smaller root module files.

leghifla 3y ago

"Refactor your codebase to put the related code together" Of course it is a goal, but not always possible. You sometimes have two (or more) conflicting "relations" in the codebase. E.g.: you are dealing with taxes in various countries. Do you group by country or by kind of taxes (on sales, profits, earnings, energy, real estate...) ? The right answer really depends on how your team is organized and how you are making changes.

froggit 3y ago
> E.g.: you are dealing with taxes in various countries. Do you group by country or by kind of taxes (on sales, profits, earnings, energy, real estate...) ? Seems like you would be dealing with one of 2 reasonably well defined problems in this case. How to group would follow logically. It's either: 1) "If i will be dealing with one specific type of tax at a time and how it is applied in different countries. (i.e. What are the sales taxes in UK, France, and Germany? )" Group by tax. OR 2) "If i will be looking at one country at a time and their assorted taxes. (i.e. What are the taxes in the UK for income, sales and value added?)" Group by country. Else "i have failed to properly define the problem." that's gonna be the problem.
- Bjartr 3y ago
  How about when supporting both use cases? A multinational company might need the former for people making decisions across the whole company, and a country specific department doesn't need anything but what's relevant to that country. You could make two tools, but now you're duplicating implementation. Factor out a shared library/service/modularization-approach-de-jour? Good idea, but we're back to the question of how to structure things. You don't always get to enforce that "OR"

jbenoit 3y ago

1. The author links to this file as an example: https://github.com/Semantic-Org/Semantic-UI/blob/49b9cbf47c172c65dc265d213c609ad5e651a6a9/src/definitions/elements/button.less https://github.com/Semantic-Org/Semantic-UI/blob/49b9cbf47c1... . How would you structure it better than it currently is without using sections? 2. So you have a class that has a bunch of getters and setters. Let's just assume that "generate them automatically" is not an option. You want to make it really easy to see the part of the class which is getters, and the part of the class which is setters, and then skim past that. How do you do it? 3. So you have a file that defines 3 data structures. Each data structure has a definition, a bunch of functions for parsing it, and a bunch of functions for serializing it. The author suggests that you split the file into 3 sections for the types, with subsections each for the definition, parsing, and serializing. How would you do it? Let's say the language is Rust or Typescript.

chrismorgan 3y ago
At least some of the sectioning in that file would probably be better handled by leaning into the language more, doing things like nesting selectors.
jaggederest 3y ago
> 1. The author links to this file as an example: https://github.com/Semantic-Org/Semantic-UI/blob/49b9cbf47c172c65dc265d213c609ad5e651a6a9/src/definitions/elements/button.less https://github.com/Semantic-Org/Semantic-UI/blob/49b9cbf47c1... . How would you structure it better than it currently is without using sections? Dear God it's a 3300 line file. Any way but one long 3300 line file is a significant improvement. I'm being hyperbolic but seriously, instead of button.less it should be deduplicated (less can be much less verbose, pun intended) and be a button directory with several subcomponents in it, like each top level heading. Less is a serious language that you should use the semantic features to organize your code instead of just comments. > So you have a class that has a bunch of getters and setters. Let's just assume that "generate them automatically" is not an option. You want to make it really easy to see the part of the class which is getters, and the part of the class which is setters, and then skim past that. How do you do it? You put it into a getters file and import it into the parent class. Almost every language has features for this. Or you put each attribute into its own file, if any of the getters and setters has smarter logic than just x = parameters[x]. Ideally you build classes that don't have so many attributes that it's difficult to scroll past the getters/setters in the first place - N > 8 is a significant warning sign the code needs to be split unless it's a configuration class or equivalent. > So you have a file that defines 3 data structures. Each data structure has a definition, a bunch of functions for parsing it, and a bunch of functions for serializing it. The author suggests that you split the file into 3 sections for the types, with subsections each for the definition, parsing, and serializing. How would you do it? Let's say the language is Rust or Typescript. It should definitely be in 3 files, possibly 3 folders, in Typescript: (/thing/index.ts, /thing/parsing.ts, /thing/serializing/json.ts) It's so marvelously easy to import things, you should be using modules amply to split up your code. Obviously the 10-lines-of-import-for-3-lines-of-code is too much, but seriously, imports are easy and cheap.

cellularmitosis 3y ago

Ah, yes, my favorite sort of HN reply. The author puts in a lot of effort to precisely articulate an issue which is difficult to articulate, and a commenter just dismisses the entire thing with a vague "You're holding it wrong".

slingnow 3y ago
Sometimes, you really are just holding it wrong. Should the OP have written a manuscript to make you feel better? In your mind, should a long, drawn out article only be refuted by something of similar length?
- ziddoap 3y ago
  >Should the OP have written a manuscript to make you feel better? In your mind, should a long, drawn out article only be refuted by something of similar length? It's not about "feeling better"? It's that the comment is very dismissive and sums up to "just refactor". Advice of "just refactor" (or "just do x") is lazy and ignores all context.
- Bjartr 3y ago
  > Should the OP have written a manuscript to make you feel better? Nope > only be refuted by something of similar length? No, but if you don't address the points that have been made, you're not refuting. The comment says "refactor your codebase to put the related code together", but the article already addresses some downsides to this approach. Does the commenter believe that those downsides are more avoidable than the article states? Or maybe they believe the downsides are dwarfed by the upsides? Or maybe something else. We don't know, so we can't evaluate the position effectively.
- rustyminnow 3y ago
  That would make me feel better. Without actionable advice, OP is just just grumbling. It's not helpful. > Refactor your codebase to put the related code together, and then this "problem" will disappear But how do I do that exactly? What does this even mean? I could literally put the whole codebase into one file since it is all related somehow or another.

tikhonj 3y ago

The problem is that real-world domains—or even just relatively complex software domains—do not decompose perfectly into 100% self-contained units. It's not even a limitation of any given programming language (although those limitations matter too!); we can't even have a purely conceptual ontology where everything neatly fits into exactly one slot in a neat hierarchy. That's just not how, well, anything works. It's definitely worth trying to have your code neatly organized in a way that maps to some clean conceptual model, but doing that well is going to require using every tool at your disposal—which includes ways of grouping code that don't need the sort of crisp definition and conceptual coherence of an in-language abstraction. Sections and sub-sections seem like a reasonable way to do that with our modern, painfully limited tools. If we weren't limited by needing everything to live in plain text, I'd also reach for something like a system of tags.

inChargeOfIT 3y ago

This is not always possible and a little short-sighted, especially when you are on a large, complex, established project with many contributors, where "just refactor 1.5 million lines of code, spanning 1500 files that have evolved over a 10 year period" is just something not open for debate. In those cases, and in the cases where a single large file just makes more sense or is unavoidable (IaC/build scripts, shell/sql/migration scripts, config files, etc.), the author's methods are absolutely valuable.

nightpool 3y ago
Try working on open source Minecraft projects. You will make these types of refactors monthly. The Bukkit/Spigot API has a 13 year pedigree, 10s of thousands of developers building against it, easily encompasses 1M+ lines of code across the whole codebase and needs to remain nimble in the face of unpredictable upstream changes. Watching the work some of these developers are able to pull off will definitely give you a healthy appreciation of what sorts of refactors are possible when you commit to them. > or is unavoidable (IaC/build scripts, shell/sql/migration scripts, config files, etc. This is a failure of the tooling in question. We shouldn't accept shoddily built tooling as an acceptable justification for unreadable codebases. Obviously, there are tradeoffs and sometimes you just need to get the tool out the door, but when a particular tool (like a professional IaC project) becomes some people's primary programming languages, then treating those languages like second class citizens who "unavoidably" are going to just be awful to work with is just limiting the growth of the tool as a whole. Terraform modules are a great example of this—all that ceremony and hassle just for what is effectively a single function call! If Terraform had single-file modules and a better import system than "relative file paths", I'd expect we'd see a lot more Terraform code bases with smaller root module files.