This chapter is from the book
This chapter is from the book
This chapter is from the book
We Are Authors
The @author field of a Javadoc tells us who we are. We are authors. And one thing about authors is that they have readers. Indeed, authors are responsible for communicating well with their readers. The next time you write a line of code, remember you are an author, writing for readers who will judge your effort.
You might ask: How much is code really read? Doesn't most of the effort go into writing it?
Have you ever played back an edit session? In the 80s and 90s we had editors like Emacs that kept track of every keystroke. You could work for an hour and then play back your whole edit session like a high-speed movie. When I did this, the results were fascinating.
The vast majority of the playback was scrolling and navigating to other modules!
- Bob enters the module.
- He scrolls down to the function needing change.
- He pauses, considering his options.
- Oh, he's scrolling up to the top of the module to check the initialization of a variable.
- Now he scrolls back down and begins to type.
- Ooops, he's erasing what he typed!
- He types it again.
- He erases it again!
- He types half of something else but then erases that!
- He scrolls down to another function that calls the function he's changing to see how it is called.
- He scrolls back up and types the same code he just erased.
- He pauses.
- He erases that code again!
- He pops up another window and looks at a subclass. Is that function overridden?
- . . .
You get the drift. Indeed, the ratio of time spent reading vs. writing is well over 10:1. We are constantly reading old code as part of the effort to write new code.
Because this ratio is so high, we want the reading of code to be easy, even if it makes the writing harder. Of course there's no way to write code without reading it, so making it easy to read actually makes it easier to write.
There is no escape from this logic. You cannot write code if you cannot read the surrounding code. The code you are trying to write today will be hard or easy to write depending on how hard or easy the surrounding code is to read. So if you want to go fast, if you want to get done quickly, if you want your code to be easy to write, make it easy to read.