Clean Code

A better way to produce readable, understandable and maintainable code — Part 1

cleaner please :)

Intro

Have you ever experienced difficulties to read someone else code? or even to understand it? or maybe, in your case, it’s your own code?! 😓

Writing code is an essentials thing in development. It’s not like writing a plain text or an article, it is how we express logic/process that we have in our mind in a way as efficient as possible yet also easy to read, understand or maintain by ourself or others in the future.

Then, how can we achieve a cleaner code? Well, in this article, we will talk about 10 clean code tips for JavaScript and CSS. so without further due, let’s get started! 😉

Overview

JavaScript

• Meaningful names
• Functions
• Comments
• Formatting
• Error Handling

CSS

• Part 2

Part 1: JavaScript Clean Code

Photo by Maxwell Nelson on Unsplash

Meaningful Names

1. Use Intention-Revealing Names

2. Avoid Disinformation

3. Use Searchable Names

4. Avoid Mental Mapping

5. Don’t be Cute

not everyone watch infinity war dude :)

Functions

1. Do One Thing
   Do one thing doesn’t mean do a single statement, it means to do one level of abstraction.

2. One Level of Abstraction per Function

By writing one level of abstraction, it means it’s also do one thing. this two thing is related to each other.

So, please take a look at the example below. this example is just the same with the previous example by creating chunk of function that in the same level of abstraction instead of writing one statements in a single function, but this time it will only highlight the function to give you the insight of one level abstraction per function

multiple function instead of a single statement

3. Use Descriptive Names

4. Function Arguments

The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justification — and then shouldn’t be used anyway.

• Flag Arguments

• Arguments Objects

5. DRY! (Don’t Repeat Yourself)

why would you repeat the same thing?

Comments

1. Explain Yourself in Code

You are writing code, not comments! so instead of writing your intention in a lot of comments, then make sure you are explaining it in a good code

explain your intention by creating explainable function naming

2. Good Comments

• Legal

• Informative
  a comment can be just simple as informative. especially if you want the reader to get the same perception of what you writing

• Explanation of Intent
  sometimes a comment can be more than just informative. you may write a comment when you really need to say the intent behind a decision.

• TODO Comments

3. Bad Comments

• Redundant
  it takes longer to read the comment instead of reading the code 😂

• Journal
  did you forget to use GIT? 😹

git cat says “meow”

• Noise
  what’s the need of saying an obvious thing?

you don’t say

• Position Markers
  no, just don’t that. really.

separator guy \ o.o /

Formatting

Formatting is one of the thing that maybe (just maybe) not all developers/engineers aware about it. most of them (including me 😅) focused more about result, and as long as it running, we don’t give a dman thing about formatting and just continue to the next step.

well, that’s absolutely a bad thing to be honest, since the code that you are writing right now, someday will be read by others and of course, with different habit/writing style. so.. how to solve this kind of “problem” in the future? well, it’s better for us to have at least one of coding style guide. it helps us/others to maintain the code with better visibility in the future.

talking about formatting, there is tons of coding format/style guide. and there’s still has difference point of view for each other. so instead of arguing about what’s right/best, let’s pickup and use what’s best for you. in this section, i won’t put all the style guide for javascript, but i will put most of the basic and general style guide that i think you will need to know. let’s check it out!

1. Comparison Operators & Equality

• Use === and !== over == and !=

2. Blocks

• Use braces with all multiline blocks

• If you’re using multiline blocks with if and else, put else on the same line as your if block’s closing brace

3. Comments

• Use /** ... */ for multiline comments

• Use // for single line comments. Place single line comments on a newline above the subject of the comment. Put an empty line before the comment unless it’s on the first line of a block

• Start all comments with a space to make it easier to read

4. Whitespace

• Use soft tabs (space character) set to 2 spaces

• Place 1 space before the leading brace

• Place 1 space before the opening parenthesis in control statements (if, while etc.). Place no space between the argument list and the function name in function calls and declarations

• Set off operators with spaces

5. Commas

• Leading commas

6. Semicolons
seriously? come on, just use ; 😐

;

7. Naming Conventions

• Use camelCase when naming objects, functions, and instances

• Use PascalCase when naming constructors or classes

A word about style guide

Well.. there are still a lot of JavaScript rules/style guide that not mentioned in this article. if you wanna know more than the basics things written above, just find the reference from Airbnb in the end of this article :)

ps: you may found that i’m also do lots of “not so formatting” in the example above, just ignore it 😝. but at least, now you get it :D

Error Handling

1. Write Your Try-Catch-Finally Statement First
sometimes we forget there’s still another way to handle an error apart from relying on if-else, especially when we know that there’s possibility of unexpected runtime error in a function, yet we still need to keep running up the next function

Still confused? you might wanna check this out: JavaScript Question: Should I Use try catch or an if Conditional? 😄

2. Provide Context With Exceptions
don’t leave the thrown error alone, use and make it more informative

Ending up the first part

Finally! it’s the end of clean code Part 1 (JavaScript).

Hopefully the first part of Clean Code article is helping you to understand a little bit about how to write a cleaner code in JavaScript. all the examples above are just general things that i thought would help you to understand about a few things in clean code. you may explore and find a lot more about JavaScript clean code apart from this article

And of course there’s still a lot of mistakes that i personally do when giving the example above and still got some not “clean code” thing in my example 😂. but at least, now you know it, and in my meantime, hopefully i can fix them 😉

Still got some coffee? let’s continue to Part 2 (CSS)!

References

• Robert C. Martin: Clean Code
• Airbnb JavaScript Style Guide