Photo by Clement Chai on Unsplash

The Developing Developer

Instead of a Comment, Use a Well-Named Function

Replace Explanatory Comments with Code That Explains Itself

--

Think back to your first programming class. Your first programming language. Maybe it was C. Maybe Java. Maybe HTML. As you were learning syntax rules, one of the first things you learned was how to add comments to your code. Whether it was // or /* */ or <!-- //--> or # or maybe even c or *, this new tool opened up an exciting new possibility:

If it’s not clear (to me or to anyone else) what these lines of code do, I can use a comment to explain myself.

And with that shiny new tool in our box, we got lazy.

As I work as a reviewer for Pull Request, I occasionally come across code that looks something like this:

const prepareMemberList = async (listName, fetchOptions) => {  // We need the list ID in order to get the members list,
// so check the mapping of list names to ids.
const mapping = require('../mappings/listToId.json')
const id = mapping[listName]
const list = await DB.getMembersForList(id)

// Make sure that we only get members from the database who joined
// between the startDate and the endDate
const filteredList =…

--

--

Full-stack. Remote-work. Based in Phoenix, AZ. Specializing in APIs, service integrations, DevOps, and prototypes. linkedin.com/in/alvin-lee-38662843