Ask HN: What makes a piece of code enjoyable to read?

#1

Post by whytheplatypus » Thu, Dec 26, 2019, 3:38 PM UTC

We spend so much of our time reading code - it's inescapable. I've become very interested in that experience and that aspect of software creation. In an initial attempt to figure out the right questions to ask, and maybe gain some answers, I'm hoping you'll share your experience.

What makes a piece of code miserable to read?

What makes a piece of code enjoyable to read?

How much of your time is spent reading code?

Re: Ask HN: What makes a piece of code enjoyable to read?

#2

Post by ArtWomb » Thu, Dec 26, 2019, 3:57 PM UTC

When the natural, human-readable language of the API. Is mirrored in the actual variable names and methods of the underlying source.

I just happened to be scanning TensorflowJS and MagentaJS when I saw your post so I'll single them out (and I understand Jeff Dean himself is an active contributor).

Trying to understand how they implement arbitrary neural style transfer (and how it can be further tweaked). It's all quite clear. Not just the math. But the comments are chock full of references to academic papers, blog posts, etc ;)

Re: Ask HN: What makes a piece of code enjoyable to read?

#3

Post by whytheplatypus » Mon, Dec 30, 2019, 10:06 PM UTC

ArtWomb wrote: post #2

When the natural, human-readable language of the API. Is mirrored in the actual variable names and methods of the underlying source. I just happened to be scanning TensorflowJS and MagentaJS when I saw your post so I'll single them out (and I understand Jeff Dean himself is an active contributor). Trying to understand how they implement arbitrary neural style transfer (and how it can be further tweaked). It's all qui…

I really appreciate the response!

I've added TensorflowJS and MagentaJS to my reading list.

I'll pick out a couple of things implied in your comment, if I'm interpreting them right:

- An API should feel natural, and human-readable - A codebase should have a flow or consistency through it, in naming and structure.

I couldn't agree more about the comments, it seems like the most useful comments are those that supplement a piece of code with references or context rather than reiterate the code itself.