DEV Community

Writing Self-Documenting Code 🧑‍💻📜

Matt Lewandowski on May 29, 2024

As developers, we've all wasted hours, staring at a piece of code, trying to decipher its purpose, and wondering what the original author was think...

Read full post

Charles F. Munat • May 31

Other that JSDoc/TSDoc I am in full agreement. Excellent article.

But I would also mention that consistency in naming is important. Establish a style guide and define your terms so everyone is on the same page.

For example, consider these terms. What do they mean and how do you choose between them:
get, find, make, create, choose, select, send, submit, save, etc.

Perhaps get means you are retrieving a single value from an API and list means you are retrieving a set of values. Then every function that retrieves a single value should be named get<noun> and the corresponding multiple values function, list<noun>s, e.g.,

getUsername()
listUsers()

Matt Lewandowski • May 31

Great point, thanks! I've added a new section that covers this: Establish Consistency and Set Expectations in a Team.

z2lai • Jun 4

Incredible advice. Im currently dealing with a codebase where there are several functions, addItem, saveItem, createItem all in the same app service and they all actually do the same thing with slight variations.

Charles F. Munat • Jun 4

Yep. The secret to programming is a) to break the problem down into small, easily-solvable mini-problems, then solve those in the simplest, clearest, and most consistent way, then compose the small solutions back into the overall solution. Clear style guides followed faithfully and invariably are essential, but how many companies bother? Save a penny, lose a pound.

All of this boils down to one simple thing: reduce cognitive load. Reduce cognitive load. Reduce cognitive load.

To this end, it pays also to apply design principles to your code. For example: proximity, alignment, contrast, repetition (consistency), whitespace, etc. I discuss this and more on Craft Code as well as here on Dev.to.

Austin Murphy • May 31

Self documenting code is a fine standard to follow, but you should still have code comments. I've worked with multiple developers who said "my code is self documenting so why comment?" 🤣 Then when they leave, nobody knows WHY they were doing the things they did, regardless of how self documenting the code is.

Please comment your code as well.

Rene Kootstra • May 31

The need for comments in code is the lack of tests. Comments rot very fast. Uncle Bob has excellent videos on the matter.

Chris S-D • Jun 2

Agreed, but IMHO, only when there is a potential "why?" question that needs to be answered.

I usually use linters as a great way to enforce this. Generally speaking, I only ever set linters to error if the code doesn't follow standards.

If the person has a reason to break standards, they need to put in a linter comment to allow the code that breaks the pattern and they are required to provide a reason that they are breaking the lint pattern. For those that can't be linted, we handle in PR. If you're doing something that is not obvious and you can't make it obvious, then you must provide a comment clarifying the issue and why you're doing it that way.

Otherwise, you should only ever use doc comments.

Comments should never describe what you are doing, nor how, only why and only when it's not obvious.

James Curran • Jun 4

Exactly. The code can only tell you what it does. Code comments are there to tell you what it's SUPPOSED to do.

Documendous • May 30

Very nice work, Matt! Thanks for the post.

Ricardo Esteves • May 30

Cool, nice article @mattlewandowski93 !

Georgi Hadzhigeorgiev • May 30

Nice one, but I suggest for you to include using of strongly typed IDs.

Matt Lewandowski • May 30

Thanks, great suggestions I'll add it in

Shyam raj • May 30

Wow.. Really interesting, thank u mate❤️

kwood-gmr • May 31

Good article, though I would disagree with using Enums in Typescript. The thing is that they are kind of funky and don't translate in and out of the underlying type well. It can better be expressed as:

`export const PaymentStatus {
Pending = 'pending',
Completed = 'completed',
Failed = 'failed',
} as const;

export type PaymentStatus = (typeof PaymentStatus)[keyof PaymentStatus];
`

gokayburuc.dev • Jun 4

It's a great explanation of the principle of "create a meaningful standard language", which is one of the principles that programmers should follow.

However, there are still missing parts. In particular, there is a need to add meaningful comment statements next to the codes and comment notations.

// TODO :
//REVIEW :
// FIX :
// TEST :
// OPTIMIZE :
// NOTE:
// HACK:

Comment expression notations provide the user with mobility for immediate intervention on faulty points.

Jake Wilson • May 31

I would urge caution about breaking a large function into too many smaller functions just for the sake of making it smaller. It can lead to too much abstraction that becomes less readable because you are trying to follow the code around separate, spread out methods and files etc.

Lin Pengcheng • May 31

sebkolind | ⛺ Tent.js • Jun 3

Great article! I think there are a lot of good ideas and valid points. I am not a fan of (2.) though - it seems like taken right out of the "Clean Code" book. It's a pain jumping from function to function to function, and you most likely lose context. I would like a bigger function where the entire context is visible and ready for me to read.

Corey Scheideman • May 30

Recommending the use of TypeScript Enums is an interesting take I don't often see. 😅

Matt Lewandowski • May 30 • Edited

I think Enums have their place in typescript, even if you can use types most of the time. I listed types first, as I do prefer types for most cases. Here is an example of where an enum would shine over a type though.

enum HttpStatus {
  OK = 200,
  BadRequest = 400,
  Unauthorized = 401,
  Forbidden = 403,
  NotFound = 404,
  InternalServerError = 500,
}

with a type

const HttpStatus = {
  OK: 200,
  BadRequest: 400,
  Unauthorized: 401,
  Forbidden: 403,
  NotFound: 404,
  InternalServerError: 500,
} as const;

// Define the type
type HttpStatus = (typeof HttpStatus)[keyof typeof HttpStatus];

With the enum in this case, we can utilize the bidirectional mapping. Which allows us to use the single Enum to determine the status and code of different scenarios.

console.log(HttpStatus[200]); // Outputs: "OK"
console.log(HttpStatus.OK); // Outputs: 200

Ultimately, I think that enums are a lot more verbose, making them more self-documenting. HttpStatus.OK or HttpStatus.BadRequest is very intuitive.