Editing Code and Stories

If you want to write better code - and thus read better code! - there are some ideas from story editing that can be put to good use.

Here are some commonly accepted practices for editing narratives.

• Give yourself time away from your story.
• Start by reading it without taking notes, as a reader would.
• Read again, taking notes on what works, what doesn't, how you feel about things.
• Consider how text accrues to the story.
• Consider whether your characters, tone, and theme are consistent.
• Clean up: get rid of fillers, cliches, passive voice, typos.
• Get someone else to help.
• Delete, delete, delete. Tighten your story.
• Repeat to improve.

If you're a moderately experienced coder, you'll realize that all of these apply to editing code. The fresh perspective of comparing editing code with narrative editing should give you an improved viewpoint.

Let's break these down.

Give yourself time away

You know how you look back on old code you wrote and feel terrible about it? It's not that you're not good. It's that the fresh perspective allows you to see things that you overlooked or took for granted while writing.

Same thing with all sorts of writing by the way - including blog posts. Be kind to yourself, otherwise you'll resist editing and improving things.

Start by reading it without taking notes

Take a first pass through the code to get a sense of the structure, without trying to figure things out in detail. This will allow you to remember details of how things are structured, interesting decisions made, etc.

Read again, taking notes

Take a pass figuring out whether things are "sketchy", things that need to be improved, things that are confusing to follow, things that you can't figure out without a lot of long concentration.

Consider how text adds value

This is your chance to determine whether classes are really pulling their weight or can be simplified. Do you have a generic thing that is never used in a generic way and is making things more complicated than they should be?

Do you have code that pulls its weight, or do you have a mass of code for a tiny bit of functionality that could be expressed differently?

Consider whether you're consistent

Reduce the cognitive load of reading your code by keeping things consistent. This helps in two ways.

1. You can mentally take the pattern's effect for granted as it's applied, so you don't have to understand it all over again every time.
2. You can more easily spot the pattern not being followed and thus catch issues.

Clean up

Clean things up beyond the things we've considered before.

• Typos
• Formatting
• Add good comments
• Delete old/misleading comments
• Remove dead code
• Improve your variable names
• Update references to code, designs, documentation
• File bugs and tasks to fix things or implement TODOs if they're missing

Get someone else to help

We do this regularly with code reviews, but it's also handy to have someone do an editing pass over your code. Building software is a team sport!

This usually takes longer than you doing it yourself, but it also makes the team better.

Delete, delete, delete

You've already got the code in source history (I mean - you do, don't you?). If you have unused functions, code, etc., don't be afraid to delete it an add a comment stating that something was there and can be found (helps with searches).

I've been working on software for a long time now, and I'd say that resurrecting old code is something that happens less than once a year.

Repeat to improve

You might be able to make this even better later on. Give it some time, and revisit in the future.

In closing

Editing is tremendously valuable. We have a whole set of processes and tools and practices we talk about as refactoring to show for it, but don't limit yourself to what tool vendors provide, and don't limit yourself to the automatic-and-provable code changes.

You have a huge potential to make things better as you gain perspective and experience - make good use of it!

Happy editing!

Tags:  coding writing

Home