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

How to Disable Disqus Ads on your Blog

Derivation of Reservoir Sampling

Fun with Python Iterators: Linked Lists Made Easy

Notes for November 11, 2018

Underrated Vim Option: undofile and undodir

Hot Take on Solo Travel: Starve

Alan Perlis

Book Notes: The Map of My Life by Goro Shimura

Prague

Way to remember the definition of local finiteness