DEV Community

My 3 Rules for Documenting Code

Jake Lundberg on December 05, 2023

There are a lot of arguments that have gone on over the years around comments. Many are adamant that "good code comments itself", while others favo...

Read full post

Monty Harper • Dec 5 '23

Excellent guidelines - clear, easy to remember, and perfectly logical. And let me just say that naming something to indicate what it is or does can be easier said than done. As a beginning coder, I'm often feeling my way through a problem and not quite sure what variables or functions or objects I need. I'm often sharpening my understanding of what different parts will accomplish as I go along. That means I'm often going back and re-naming things to better reflect their purpose. I might tweak a name several times to get it just right. But it's totally worth the effort. I need to be able to understand my own code as I expand on it later! And someday when I'm part of a team, I know these good habits will make me an easier person to work with.

Jake Lundberg • Dec 5 '23

Thanks @montyharper!

First, let me give you a high five ✋ for making an effort to go back and update your code after gaining a better understanding. That's such an essential piece of maintaining code that too often I see getting ignored. Keep that up!

In regard to naming being difficult...when I encounter something that's difficult to name it's usually because I didn't break things out in the best way. In fact, I like to use naming as a personal "flag" to indicate if I'm on the right track or not. If I can't come up with a good name that clearly defines what my code is doing, it's almost always a sign that I need to rethink my approach.

Have you noticed something similar? Or have you experienced something different?

Monty Harper • Dec 5 '23

Well, yes... but then I'm at a stage where I'm still mostly coding things that are a bit beyond my current ability, so I'm usually on the wrong track, until I get it right. I will definitely keep what you're saying in mind, though, because it sounds spot-on. I'm also a songwriter, and I've experienced this with song titles; if I'm not sure what to call a song then it probably isn't the title that's the problem. It probably means the song has a weak chorus or an unclear focus, and I need to spend some time re-thinking what the song is really about.

Jake Lundberg • Dec 5 '23

Great comparison! 😄

Valeria writes docs • Dec 7 '23

Great tips. I really enjoyed reading your advice because is practical and I believe they definitely improve code readability. I have a suggestion and a question.

My suggestion is that, because functions are actions, their names should contain a verb as a prefix, example: sumTotal. When their main function is to return something without changing it, the name should start with GET: getName. And when they return a boolean, their name should start with IS: isCold.

My question is: what do you think about using comments to warn colleagues about parts of code that shouldn't be modified? Sometimes is not obvious when certain functions affect other parts of the codebase

Jake Lundberg • Dec 7 '23

Thanks @valeriahhdez 😃

This is a great suggestion! What you're describing is generally how I personally like to handle naming. With that said, the specific patterns used in naming will need to be decided per team based on needs and preferences. It will also depend on the kind of programming being done.

For example, in functional programming, you may want to prefix functions that return a boolean with the name of the subject being tested. So rather than isEnabled, if we were testing a feature flag, the function might need to be featureIsEnabled. But in Object Oriented Programming, since the method is already on an instance of a class (or the class itself if it's static), the method could be isEnabled because the subject is clear when calling it (ie. someFeature.isEnabled).

So in general, I agree with your suggestion, but there will always be nuances to look out for.

In regard to your question, I absolutely think comments should be used to warn other developers of things. If there's a known use case that isn't obvious they need to account for, or some solution was tested and it didn't work for whatever reason, things like this should definitely be commented so the same mistakes aren't made in the future.

I would like to call out one thing though...you specifically mention, "parts of code that shouldn't be modified". In general, I wouldn't recommend documenting something as "DO NOT MODIFY" or similar. Instead, I would suggest documenting the things that need to be taken into account if the code IS modified. The reason being is that none of us can predict the future. It's possible there will come a time when that code must be modified (due to a bug, changing requirements, a needed optimization, etc). When that happens, it would be beneficial to have a list of things that could be impacted. I'd be curious to know if you (or others) have different perspectives on the subject though.

Valeria writes docs • Dec 7 '23 • Edited

I couldn't agree more with this nuanced perspective on my comment. You put it in better words than I could.

Alois Sečkár • Dec 13 '23

This is awesome. A great and balanced mix between "always write comments everywhere" and "no comments required in really clean code". And you explained it in very intuitive way. This should be taught in schools and programming courses.

Jake Lundberg • Dec 13 '23

Wow, thank you @aloisseckar! I'm honored to get such a compliment 😍

Rulo Kobashikawa • Dec 7 '23 • Edited

Thank you for this guidelines. I found good naming (WHAT) leads to better code (HOW) and I think focus on WHY with the comments is a very good idea because there is no need to redundancy of explain WHAT, if naming is good, or HOW, if code is legible.

Clayton Kehoe • Dec 5 '23

I agree with all this. I find comments that just repeat exactly what the code does distract from trying to understand the code

Jake Lundberg • Dec 5 '23 • Edited

I agree @kehoecj

Very frequently when I see this being done, I notice it stems from 1 of 3 issues:

lack of experience. the author may not know any better. they heard that they should be documenting their code and this is what they think that means.
a blanket statement was made requiring that literally everything must be documented by comments.
the code is overly complex and is difficult to understand on it's own.

Obviously there are other reasons, these are just the common one's I see most frequently. But in all these cases, the solution is education. Whether that's teaching an individual or an organization, educating people on what documentation provides benefits is essential.

What's been your experience on the subject? Do you see this happening for other reasons than the ones I mentioned above? How do you address it?

Pixelrella • Dec 5 '23

Love this! To boil writing clean code down to these three rules is really practical. In the end what you need when you read code is exactly that: What? How? and Why?.

Taking more time to write descriptive code saves so much time in the future!

Jake Lundberg • Dec 5 '23

Taking more time to write descriptive code saves so much time in the future!

😍 I couldn't agree more!

Griff Polk • Dec 13 '23

AGREE AGREE AGREE. My code about 5 years ago was SO much messier than it is today.

Griff Polk • Dec 13 '23

Also, notice the fact that Google, in their Bard updates, lists “what” and “why” for each update. They know.

Jovian Hersemeule • Feb 11

Thanks for sharing ! I share your feelings about what is the purpose of a name in source code (telling what it is), and what is making comments useful (explaining why this piece of code exists). Thank you for putting words on these concepts, I'm going to share your article with my dev team.

There is one more point I would like to mention about writing comments, that is also valid for any text you have to write : you have to think about who is going to read your comment. If it's the future you, you'll probably write barely no comment, or specific keywords to remind you why you did it that way. If you are working on closed-source code, with French speaking people only, it's probably better to write comments in French language. If you have many junior devs in your team, you can give some tips to maintain this piece of code or name the design pattern you used.

But most of all, you have to think about what the reader might be looking for. Yes, most of the time it would be a dev tasked to develop a new feature. But at one point someone would have to fix this code : so you may add a link to a relevant test to execute, that would help this future bug hunter to figure out what is going on. If it's an API meant to a specific purpose, like adapting some legacy code, you can warn the user in your comment "if you aim to write a new component from scratch, please prefer this ".

This is a practical example of a link in a javadoc comment (tip : Ctrl + Click with a modern IDE brings you to the referenced method) :

/**
  * If you don't deal with legacy code, prefer to use {@link fr.company.package.OtherClass#readNewFashion()}
  */
public Item readFromLegacy() {
// code
}

You have to think also of the location of your helpful text. For example, some IDE show doctrings as a tooltip when your mouse hovers a class name, that makes your comment visible in every place the class is used. Last but not least : your VCS (git) commit message can be seen as a comment of a change, and imho, it's even more important to write that why for this change.

Thanks again, and happy hacking too !

Matthew Curland • Dec 6 '23

These are good general guidelines, but I think one other important (sub) category is a why not. Whenever I find myself removing the obvious one line fix (that didn't work) and replacing it with more involved code I track the obvious code in a comment and explain why it did not work. This saves time in the near term (for code reviewers) and long term maintenance, when you or someone else may be tempted to revert to the obvious (wrong) code.

Other things to add are to minimize external references and explaining from the perspective of the current code, not the caller. If you must reference how the code is called it should be done generically ("if a caller needs X, they can do Y" etc). "This fixes issue 12345" is meaningless if the code has outlived the issue db or moved to a different project, and callers can change over time.

Parth Upadhye • Dec 6 '23

Excellent points. However, the landscape has changed. We code in a multilingual and global space where English is no longer a criteria for employment.
FYI: I have read the most bizarre method and object names. However, in context of the programmer's language, it made sense.
Fortunately we now have AI to translate things for us. Before long, we will be only looking at what lies within curly brackets (I know there is a word for that).

Jake Lundberg • Dec 6 '23

I'm a bit confused with your response. Could you elaborate a bit on where the language of the comments was brought up? If anything in my post caused this confusion I would like to fix it.

For your second part, I'm afraid I have to disagree with you about the use of AI, friend. While it has certainly made us more productive, and has added tremendous power to our workflow, so long as humans are writing code (which I do believe will be the case for at least a few more years) we will need clean, well organized, understandable code...which includes good naming and comments. Even if AI wrote it, at some point (at least currently) if a human must read it, it needs to be easily understood. I don't personally know any developers who are using AI to translate every code block they look at. But perhaps I'm wrong. Have you seen something different?

Frulio • Feb 15

Nice article, I also find useful to comment the HOW when is an obscure optimization or a particular algorithm that is not obvious for everybody (those can take a while if you don't know them)

Mariondeleon-ux • Jan 29

It's one thing to use coding in spontaneous ways; there's another and better reason for staying within this framework that forces one to use a target structure successfully.