Tidy First?

Chapter 5. Reading Order

Let’s say you’re reading a file (we can have the debate about whether source code belongs in files some other day). You read the whole file, and you get to the end and there it is! The detail that would have helped you understand all the rest of the file.

Reorder the code in the file in the order in which a reader (remember, there are many readers for each writer) would prefer to encounter it.

You’re a reader. You just read it. So you know.

Resist the temptation to apply any other tidyings at the same time. Likely in reading you will have noticed other details that make comprehension and change harder than they should be. There will be time for those details later. Alternatively, tidy those details now and shuffle the reading order in a later tidying. Don’t mix.

Some languages are sensitive to the order of declaration of elements. That is, switching the order of declaring function A and function B will produce different execution results. Be careful in such languages. Maybe don’t reorder the whole file, just the bits most relevant for readers.

No single ordering of elements is perfect. Sometimes you want to understand the primitives first and then understand how they compose. Sometimes you want to understand the API first and then understand the details of implementation. You’re the reader, so use your judgment and (recent) experience. What order would you have liked to encounter? Give the gift of that sequence to the next reader.