JavaScript is a very forgiving language. It’s easy to write code that runs but has mistakes in it.
In this article, we’ll look at the best practices for laying out JavaScript function code and documentation.
Use Blank Lines to Separate Parts of a Function
Any code that’s inside the function’s body should be grouped into related paragraphs so that we can see them easily.
Use Standard Indentation for Function Arguments
Function argument should be indented if they overflow the first line.
For instance, we may write:
const readFile = (
fileName,
employeeCount
) => {
//...
}
and call it as follows:
readFile = (
fileName,
employeeCount
)
This is easier to read than having everything in the same line.
Laying Out Classes
We should put the constructor first in the class. Then we add methods.
For instance, we write:
class Person {
constructor(name) {
this.name = name;
}
greet() {
//...
}
}
We have the instance method greet below the constructor.
If we have More than One Class in a File, Identify Each Class Clearly
We should be easily identify classes that are in the same file.
For instance, we write:
class Animal {
//...
}
class Person {
//...
}
to write 2 classes. We make them clear that they’re classes with the class keyword and PascalCase names for each class.
Put One Class in One File
Putting one class per file is a good idea.
We may want to do that to make finding them easier.
Give File a Name Related to the Class Name
If we have one class per file, then the class name should be related to the file name.
This way, we can find the class by their file name easily.
Separate Functions Within a File Clearly
Having blank lines between functions let us read them easily.
For instance, we can write the following:
const max = () => {
//...
}
const min = () => {
//...
}
This way, we can see our function code easily.
Sequence Functions Alphabetically
We can separate functions alphabetically so that we can look for them easily with our eyes.
So we can write:
const bar = () => {
//...
}
const foo = () => {
//...
}
Self Documenting Code
Having self-documenting code is important. We want our code to mostly explain themselves so that everyone else can understand it when they read them.
External Documentation
Even though the code is self-documenting, external documentation is still important.
They’re for high-level decisions mostly, between business requirements documents and the code itself.
Unit development Folders
Unit development folders is an informal document that has notes by developers that are written during development.
It includes justifications for decisions and top-level design standards, and related knowledge that aren’t covered in code.
Detailed-Design Document
This is a low-level design document that let us document class and function level design decisions.
It documents the cases that we considered and alternatives that were skipped.
Programming Style as Documentation
The internal documentation is done with a clear code.
Code-level documentation is done with a good programming style.
Even if a piece of code doesn’t have comments, we should still be able to understand it.
So the name should be descriptive, spacing should be good and consistent, and code groups should be small.
To Comment or Not to Comment
It’s easy to write comments poorly. And bad comments are more damaging than helpful.
Therefore, we shouldn’t write too many of them.
Keys to Effective Comments
Wrong comments should be removed. They’re misleading and may lead to developers making wrong decisions.
If they’re just a repeat of the code, then they should definitely not be written.
If there’re any tricky parts of the code that needs explanation, then we may need comments to explain them.
Markers shouldn’t be left in the code. If we use markers to mark defective code that should be fixed, then we should just fix the code.
Conclusion
We should aim to write self-documenting code.
To do that, we have good spacing and names.
Code groups should be short and clear so that they’re easy to read.
Blank lines and indentation are important for readability.
