DEV Community

Discussion on: "Do not comment on your code, it should be self-documented". Well... I don't agree.

View post
Collapse
 
joelbonetr profile image
JoelBonetR 🥇 • • Edited

Ok so there are like 100 comments that I honestly won't read (I was eager to read the first 10 but got tired at 5).

What whas that? It's honesty. We all should practice it when coding, because we know what we are doing at the time of coding whatever but we should be honest and think that "My future me will love to see comments on this code".

"Yeah but there are functions that are SOLID and don't need comments because blah blah"

I had the exact same conversation with a colleague the other day so let's mimic it:

const getUserById = async (id) =>  await User.findOne( { where: { id: id } } );
Enter fullscreen mode Exit fullscreen mode

Is it straightforward, isn't it?
But how do you know what it returns?

"But Joel, it returns a user, A USER!"

Nope, it returns a Promise that hopefully will retrieve a user (as long as it exists in the DB).
And me and you, and the rest of the team will love having this information without the need of Ctrl+Click over the function name to see what is doing behind the scenes.

/**
* Retrieves a user from the DB based on the ID
* @param {number} id 
* @returns {Promise<Object>} User
*/
const getUserById = async (id) =>  await User.findOne( { where: { id: id } } );
Enter fullscreen mode Exit fullscreen mode

So when you are about to use this function you get:

Here it is! Inference! Beloved inference.

Moreover if you use TS pragma

// @ts-check
Enter fullscreen mode Exit fullscreen mode

at the top of your JS file it will use TS when it's important, in dev time.
Without adding TS as project dependency plus without the extra bundle time of compiling/transpiling TS into JS.
It will use JSDoc to type-check your functions and variables. VSCode will handle it out of the box.

So if you try to do something like passing a string it will correctly complain like that:

Look how cool it looks like!

// @ts-check
import { User } from '../db/models/users';

/**
 * Retrieves a user from the DB based on the ID
 * @param {number} id
 * @returns {Promise<Object>} User
 */
const getUserById = async (id) => await User.findOne({ where: { id: id } });

/**
 * Gets a cookie value by name
 * @param {string} name
 * @returns {string}
 */
export const getCookie = (name) => {
  const value = `; ${document.cookie}`;
  const parts = value.split(`; ${name}=`);
  if (parts.length === 2) return parts.pop().split(';').shift();
};

/**
 * Retrieves the user ID from the browser cookies
 * @returns {number}
 */
const getUserFromContext = () => parseInt(getCookie('uid'));

/** @type {User} */
const currentUser = getUserById(getUserFromContext());
Enter fullscreen mode Exit fullscreen mode

It looks even cooler in VSCode as it changes the color for the JSDoc when properly written:

Sooner or later I receive either a "you are right" or a "you were right" about that.
I had been in enough projects to say that this is a must.