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.

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".

The author didn't put any effort into actually trying to articulate a concrete example of a system that was already well-architectured but also needed section headers. All of the examples they brought up would be better-served by more sensible refactors that didn't go to one extreme (4 line files) or the other (2000 line files). I'm sure there are rare files where having section header comments really is helpful, but personally I've never found it a useful way to organize my code, even in >500k LoC projects.

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?

> Sometimes, you really are just holding it wrong.

Yup. We all are. This is only a problem because editing raw plaintext code as single source of truth is a bad idea, and we're reaching its limits. "Split or don't split" is one of many holy wars that can't be solved, because they happen on the Pareto frontier. The only way to move forward is to accept that different coding tasks need different representations, and the computer should synthesize them for us, and we generally should not touch the underlying single source of truth, anymore than we manually poke in assembly files generated by our compilers.

People have been saying this forever. History has shown they were wrong then and history will eventually show that you're wrong too.

I beg to differ. The industry existed only so long, and while some people have been (rightfully!) saying this since the early days, the market opted to push a shitty solution to its limits, and only now we're starting to feel the pain of pressing against those limits.

I can't imagine it will ever become mainstream to store source code using anything but plain text unless we stop using Git and representing files and directories in the classical Unix fashion.

The alternative to plain text is programming-language specific version control and source code formats, and managing codebases using some external database tool, or something similar. It also means you can't easily interoperate with existing plain text code.

I predict the only way people will switch is if there's some overwhelming competitive advantage in storing code as something other than text files, to the point where business competitors will go bankrupt from not upgrading technologies. And then the open source community will adopt it after the industry does.

We can keep storing code in text files, that's not the point. Point is, we should not be editing this storage form directly, but rather its slices and projections relevant to the task at hand.

They should at least address the actual points raised by the article (which does already touch on the trade offs involved in doing what the commenter suggests, none of which were addressed by their comment). As it stands it sounds like they’re responding to nothing more than the title of the post.

It’s a shallow criticism by HN standards.

> 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.

>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.

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.

1. The author links to this file as an example: 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.

> 1. The author links to this file as an example: 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.

> Dear God it's a 3300 line file. Any way but one long 3300 line file is a significant improvement.

I happily hack every day on a project that is self contained in a single 12K line (and growing) file. For me, splitting into multiple files would have negative utility. Everything is essentially in one place. I can find anything I need for my project with '/' search very quickly in vim.

My style is obviously not for everyone but it works great for me. I programmed for decades with traditional file splits and only in the last few years have I switched to single file. I have little interest in going back. For me, it is liberating to stop thinking about directory layout entirely. It also helps me to use simpler tools (I only use vim with no plugins) in part because I don't need help managing multiple files.

100% agree if it's your project it's your project. I'm just coming from the perspective of a very team-oriented style where you absolutely want to limit the complexity per file for understanding.

Also I don't envy you reviewing the diffs when you add something that affects e.g. indentation on the file.

> You put it into a getters file and import it into the parent class. Almost every language has features for this

Wait, what?

So you can do this in C/C++ for sure. #include is not just for imports. But Java? C#? How!

C# at least supports the notion of partial classes that can have their definition spread over multiple files: https://learn.microsoft.com/en-us/dotnet/csharp/programming-...

Ruby has mixins and Python supports multiple inheritance. Go encourages composition over deep nested hierarchies.

Many main stream languages support this kind of functionality.

Superclasses, interfaces, or module import. I'm no Java or C# expert but you have to lean into the conventions the language provides. I would probably have a separate small POJO that stores the configuration for the class if it had so many getters/setters I wanted to split them out.

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.

"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.

> 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.

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"

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.

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.