Breaking Up Large Files Into Sections

It’s a 2,000 line behemoth. It’s hard to browse or easily find what you are looking for in there. What can be done? This article isn’t about actually dismantling the file (although that would be a good one), it’s mostly about what to do when you need to leave the file that way.

Don’t Make Files That Big

Ideally, you don’t let files get too long. The longer the file the more likely it is that it’s become a dumping ground rather than a proper cog in the machine.

We’re talking about authored files here. Your production `style.css` file probably is quite long, but it’s probably compiled from smaller bits, organized into sensical parts.

If your authored files are already too long, can you find a way to break it apart that makes sense? If you can, it’s probably a good idea. Perhaps your monster `user_controller.rb` can be split up into concerns which the main controller can inherit.

Abstraction at work!

But let’s say, for whatever reason, it makes sense to have a mega-long file in your project. It needs to be that way, and you need a way to make it more manageable. Maybe we can have a little fun with it.

ASCII Art Blocks

If you do a lot of scrolling up and down the file, perhaps putting a bunch of space between sections is helpful. And then how about a big commented block of ASCII art text to label the section?

  ______                       
 |  ____|                      
 | |__ ___  _ __ _ __ ___  ___ 
 |  __/ _ \| '__| '_ ` _ \/ __|
 | | | (_) | |  | | | | | \__ \
 |_|  \___/|_|  |_| |_| |_|___/

If you use an editor with a “mini map”, these can really stand out, as pointed out by Xah Lee:

Comment Blocks

Maybe it’s just the space and the big block of commented code that stands out, so instead of being fancy artistic, maybe get real practical and label each section with metadata.

/*

  Section: Form Styles
  Purpose: To style form elements like <input>s and <button>s and such.

  Author: Chris Coyier
  Last updated: September 28, 2015
  Favorite TV Show: Northern Exposure

*/

Weird Indentation

Code tends to cluster to the left. It looks weird when things are indented pretty far without nesting that leads to it. Perhaps you can use that do your advantage.

.main-header {
  background: black;
  color: white;
}

              // *****************
              // -----------------
              // FOOTER STYLES
              // _________________
              // *****************

.main-footer {
  background: white;
  color: black;
}

Long Lines

Especially if you don’t have wrapping/soft-wrapping turned on, super long lines can be a nice way to break things up.

// XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Things You Can Search For

If you used a convention for how you named sections, that makes searching through the project (or parts of the project, or single files) yield good results for finding those sections.

Searching is so much faster than scrolling!

Use Code Folding Feature

If your editor features code folding, make use of it! The whole point of it is to temporarily visually hide blocks of code so they aren’t distracting.

Sourcemaps

If you write in a language that compiles to something else that the browser uses (e.g. Sass, CoffeeScript, Closure compiler, etc) it may offer source maps, meaning the DevTools can tell you what line a bit of code is on in the original authored file, not just the compiled version. That way you know exactly file you need to go to to edit it:

And you know what line as well, so you can jump right to it no matter where it is.

Does your editor help you in special ways?

Is your editor really good with it’s “Find in Project” feature that jumps you right to the line? Use it!

Does your editor have some cool way to jump around in files? I know “Go To Symbol” is pretty popular in Sublime Text and Jetbrains has it (I’m sure many others as well).

Does your editor (or an add-on) have some way to tab through sections of code? Try it!