Use Lists, Not Commas, In Technical Writing


This is an opinion, so feel free to disagree.

My Advice

Whenever you have an enumeration (whenever you list stuff out) that’s written inline with commas, break it off into an explicit list, either unordered (bullet points) or ordered (with 1., 2., etc.).

This makes the enumeration obvious and easier to read.

Examples of Comma Separated Enumerations

Contrived example

A homeomorphism is a bijective, continuous function, whose inverse is also continuous.

Actual Example from a Friend’s Blog

His blog no longer has this, but the original form was:

Pure functions are often defined as those without side effects. Side effects tend to be handwaved as “things that affect hidden state”, “things that are confusing”, “things that are bad that you can do in C++ because C++ is bad”, and other such bogeymen.

Rewritten forms

Homeomorphisms

A homeomorphism is a function that is:

  • bijective
  • continuous
  • is also continuous.

Side Effects

Pure functions are often defined as those without side effects.

Side effects tend to be handwaved as:

  • “things that affect hidden state”
  • “things that are confusing”
  • “things that are bad that you can do in C++ because C++ is bad”
  • other such bogeymen.

Caveats

It’s important to put the redundant info in the header for each list, or else it sounds weird when read.

Example

A homeomorphism is:

  • a bijective function
  • a continuous function
  • is also continuous.

Repeating “a function” sounds weird.

Takeaway

Go forth and write lists that people can read at a glance. Don’t make your readers work as much as possible, because God knows they’re lazy.

Errors

If you find any errors, or if I’m just plain wrong, or you want to tell me something, feel free to tell me.

Related Posts

Handy command line benchmarking tool

Stan Rogers

Ultimate Hot Couch Guy

Quote on Java Generics

The Programmer Tendency

Figure out undocumented JSON with gron

Mental Model of Dental Hygiene

Book Review: Swastika Night

Is there a name for this construction?

Fun with negation and idioms