DEV Community

Your code should tell a story: Tips for writing code for others to read

Tom Collins on February 24, 2020

When we write code, we are also writing a story for other developers. Here are a few tips on how we can write code for our future selves and other...

Read full post

David Gavilan • Feb 25 '20

I think userPassedCourse should be called userFailedCourse. Or at least, having a low mark suggests or low attendance suggests failure. But then, you switch passing false to passing true from one example to the next, so even if you are trying to refactor it to make it more readable, I'm getting really confused by the example.

Tom Collins • Feb 25 '20

Changed to:
user.result > 40 && user.attendance > 50

Gábor Soós • Feb 24 '20

Nice examples for promoting Clean Code!

Intention revealing code is prior to code length. There is a different tool for code length and it's called minifier.

Charles Szilagyi • Feb 24 '20

Nice one, should get more ❤️s!

By the way, I guess you meant

const entity = {
  UNDERGRAD: 'underGrad',
  POSTGRAD: 'postGrad',
}

getResultsFromDB({ entity: entity.UNDERGRAD, courseId: 'SCIENCE_101'})

Tom Collins • Feb 24 '20

haha yes. That would very much negate the advantage here!

Nice spot. Article updated.

Alex Lohr • Feb 25 '20

If you can, use TypeScript to document the API. The reading flow is better than with plain JSDoc. The IDE integration will make working with your code a pleasure. Pro-Tip: use JSDoc comments to comment more complex types - this documentation will then be shown on hover in modern IDEs.