This site runs best with JavaScript enabled.

Newspaper Code Structure

Software Engineer, React Training, Testing JavaScript Training

Your code should read like a newspaper article. Important stuff at the top, details at the bottom. I have a particular convention for my...

Your code should read like a newspaper article. Important stuff at the top, details at the bottom. I have a particular convention for my code that leverages some of the querks of JavaScript to produce much consumable code. I want my code to be easy to read by people regardless of their editor (or without an editor at all, like on GitHub).

Here's a common way to write code that I see all the time. Pretend that you need to use this module. See how fast you can find out what the api to this module is (and objects from the module):

1export const bar = {
2 some: 'property',
3 someFunction() {
4 // with plenty of lines
5 // and more stuff
6 // because... reasons...
7 },
8 someOtherFunction() {
9 // because we need it
10 // it's really important...
11 },
12 someOtherProperty: true,
13 anotherFunction() {
14 // forgot about this one...
15 // why is it here, instead of at top?
16 // who knows... Doesn't affect functionality right?
17 // but it might impact readability...
18 // especially if it gets long and stuff
19 },
20 dontForgetMe: '!!!!',
21 ohWaitNeedThisToo() {
22 // yet another function
23 // man, I need a few of these don't I?
24 // what other functions does this "bar" thing have?
25 // does this file export anything else? I guess I'll have to search around and find out...
26 },
27}
28
29export function longFunction() {
30 // I could really use a doughnut right now...
31 // Sometimes functions need to do a lot of things
32 // You should keep these functions short
33 // Otherwise your code is hard for a reader to consume...
34 // and that makes me sad :-(
35 // and confused
36}
37
38export function meToo() {
39 // make sure you scroll around the file
40 // so you know EVERYTHING that this module exports
41 // Because with this method, discovering that is a little difficult.
42 // There's gotta be a better way!
43}
44
45export const thereIsABetterWay = true

What's the problem?

I hope that I illustrated the issue in the comments in the code there. The main problem is when I come in to maintain this file or even consume it. I have a hard time knowing what the API into this module is. This just makes reasoning about that code much more difficult. I also personally think that it's harder to read, but that could be just because I'm used to my own method now.

Is this for real?

I used to work on a huge Backbone application (150k+ lines of code). Many of our Backbone.Views looked very much like the bar in this file (really tall, hard to know what functions are available on the view). In fact, one of the worst views in the application was 2000+ lines of code! Now everyone knows that is a bad practice just in general. But even if it had been that long, using my suggested different approach would have really helped maintaining that monster.

A different approach...

Now, see how fast you can determine the api to the rewritten module (some comments different, so read those too):

1const bar = getBar()
2const thereIsABetterWay = true
3
4export {bar, longFunction, meToo, thereIsABetterWay}
5
6// function declarations
7function getBar() {
8 // main "export" for the function
9 return {
10 some: 'property',
11 someFunction,
12 someOtherFunction,
13 someOtherProperty: true,
14 anotherFunction,
15 dontForgetMe: '!!!!',
16 ohWaitNeedThisToo,
17 }
18
19 // function declarations
20 function someFunction() {
21 // with plenty of lines
22 // and more stuff
23 // but I don't mind anymore, because I only read this if I'm interested in it
24 }
25
26 function someOtherFunction() {
27 // because we need it
28 // it's really important...
29 }
30
31 function anotherFunction() {
32 // forgot about this one...
33 // why is it here, instead of at top?
34 // who knows... Doesn't affect functionality right?
35 // it doesn't actually make a difference
36 // even if it gets long and stuff
37 }
38
39 function ohWaitNeedThisToo() {
40 // yet another function
41 // man, I need a few of these don't I?
42 // what other functions does this "bar" thing have?
43 // I know just by looking at the top of the enclosing function... It's obvious... Important stuff at top, details at bottom
44 }
45}
46
47function longFunction() {
48 // I could really use a doughnut right now...
49 // Sometimes functions need to do a lot of things
50 // You should keep these functions short
51 // Otherwise your code is hard for a reader to consume...
52 // and that makes me sad :-(
53 // and confused... But at least I know what the API is and it'll make consuming and maintaining this file much easier
54}
55
56function meToo() {
57 // Don't need to make sure you scroll around the file
58 // so you know EVERYTHING that this module exports
59 // Because with this method, discovering the exports is obvious
60 // It's just at the top of the file. What I see when I first open it up
61}

Why is this better?

Hopefully I explain that well enough in the comments in the code, but you should notice right from the get go at the top of the file that it's much easier to know what the API to this module is. If I'm tasked with maintaining this module or using its API, I know exactly what to expect from this file.

Note, this leverages the "quirk" in JavaScript with function declarations which basically amounts to the function definition and declaration getting hoisted to the top of the closure. This is why you can put function declarations after the return statement.

What about ES6 Classes and/or this?

This kind of breaks down with Classes because they must be structured like this:

1export default class Person {
2 constructor() {}
3 walk() {}
4 talk() {}
5}

Again those functions can get long and you're pretty much in the same scenario as the first sample of code. This is one of my personal beefs with classes. Lots of people just say that your IDE should help you, but your IDE doesn't help much if you're just looking at the code on GitHub and that's important to me because I'm pretty involved on there and it's also important to me that I don't enforce what editor/IDE people use and that its consumable by anyone.

So what's the solution? I don't know to be honest. I'd like to say that the solution is just to keep your code clean and short, but in my experience, I've found that just doesn't cut it sometimes.

Keep files/functions small

Most of these problems kind of go away if you keep your files and functions small. But sometimes that's hard to do and abstractions can only get you so far. I use this code structure even if the amount of code I have is small.

Closing

Thanks for reading! Catch me on twitter if you have comments / want to discuss :-)

Discuss on TwitterEdit post on GitHub

Share article
loading relevant upcoming workshops...
Kent C. Dodds

Kent C. Dodds is a JavaScript software engineer and teacher. He's taught hundreds of thousands of people how to make the world a better place with quality software development tools and practices. He lives with his wife and four kids in Utah.