The Virtue of Brevity

"If it is possible to cut a word out, always cut it out." - George Orwell

On my last project, there was a substantial guidelines document for how to do code review. I read that document multiple times, but I could not tell you anything that was in there.

This is not to say that the guidelines were disagreeable or poor, but that there was way too much information for the document to be useful.

I contend the guidelines would have been better if they were shorter and more concise.

For the document, and anything else, being brief serves two purposes.

1. It becomes more readable, and thus more useful.
2. It respects the time and abilities of those who read it.

When we write, it's to get something across. Successful communication is the goal, and brevity is the key to successful communication.