DEV Community πŸ‘©β€πŸ’»πŸ‘¨β€πŸ’»

DEV Community πŸ‘©β€πŸ’»πŸ‘¨β€πŸ’» is a community of 966,155 amazing developers

We're a place where coders share, stay up-to-date and grow their careers.

Create account Log in
Tykok
Tykok

Posted on • Updated on

Please, comment your code...

Why should I comment my code ?

If you're actually code in Java, JavaScript, Python, PHP. You're probably hear about technical documentation and some things like :

And if you had not heard anything about "how to comment your code". So you were, you are or you will be confronted to THE question :

"What this code do ???"

And you know how it's painful when something doesn't work and you can't understand WHY !

Rage developer

When you use an external program, your reflex is to read documentation about this program to understand how to use this.

When you comment your code, the objectives is the same. You'll write some details for you in the future or for the people who use or improve this code.

Objectives

The objectives is multiple, just think about you in 2 years in this code. You'll be happy to see somes comments who explain what is this weird classes you added before πŸ˜†.

Now, if you don't code alone. Think about you're associate will read and use your code.

And PLEASE, think about all people who use your code in the future if you're make an open source program.


I think you understand now, when you comment your code you actually :

  1. You saves time for you, and for other peoples
  2. Describe, and have a readable code
  3. Your code will be accessible

When should I comment ?

It's recommended to comment your class, you're function and use inline documentation when is necessary. I think it's the minimal requirement for a readable code.

A code has commented, is a readable code. BUT, use comment whith thriftiness.

Of course, if you're function is named sum for example, and take two arguments. It will be really simple to know what the function do.
Personaly I think you should comment for function when the function is over 10 lines, and it's required for classes.

And please remember, a developer does not only code.

A developer maintain, debug, keep an eye on evolution, document, and think how to resolve problems.
So please, comment your code and make happy the "you" of tomorrow and all people who read your code. And you'll make a step to become a programming god πŸ˜ƒ.

God developer


Tell me if you have any suggestions, or remarks and of course if this article was interesting.
There is so much to say about this, feel free to express your point of view, so don't hesitate. 😜

Top comments (25)

Collapse
 
codingchili profile image
Robin Duda (they/them)

Knowing when to comment is as important as knowing when not to comment. Comments introduce ambiguity and can be misleading as well as increase maintenance costs. The second best code is the code that doesn't need documenting, the best code is the one that needs not be written. When we are commenting it needs to be in regards to the target audience as you mentioned, clear and concise.

Javadoc is great, especially if there are downstream consumers. Apply javadoc to all public API's, which targets the consumers. Inline comments target the project developers. We should also consider other forms of documentation, tests being critical. A test is documentation, an example of usage and verification all in one - that is even providing guarantees about being up to date.

Collapse
 
citizen428 profile image
Michael Kohl

That's why people say that good comments explain the why, not the how (exceptions apply, as always). If one feels a need to comment on the how of a piece of code, it may be time to consider a refactor.

Collapse
 
mattmoranjava profile image
Matt Moran

Where I work, we use JIRA to track issues, and every commit message starts with the JIRA ticket ref so commenting the why of it is largely unnecessary. Very very occasionallly you'll see people commenting the how of it, as in how to make use of this method if it's somehow impossible to write it using clearer, cleaner code.

Thread Thread
 
tykok profile image
Tykok Author

Yes, that's the message I'm trying to get across.
When you take a code that is not yours; you're going to spend time understanding what this X function does, and how you can use it for example.
It's a real benefits.

Thread Thread
 
citizen428 profile image
Michael Kohl • Edited on

@mattmoranjava

commenting the why of it is largely unnecessary

There are so many "whys" that are usually not part of a JIRA ticket:

  • Why did we choose this algorithm even though another one is more commonly used for this use-case?
  • Why are we doing <insert unintuitive thing> here that we wouldn't need to be doing in a perfect world?
  • Why did we reinvent this specific wheel even though most users of framework X usually use library Y for this?
  • etc.
Thread Thread
 
codingchili profile image
Robin Duda (they/them)

In my opinion design decisions must be documented. Can it be explained in one line just write an inline note. Otherwise just use a design notes field in jira, then you can just refer to it.

"The why" contains lots of information that we don't want to go missing. Did it take a day to figure out why z is the best algorithm? Document that stuff or you will keep losing days for the rest of eternity.

Thread Thread
 
citizen428 profile image
Michael Kohl

Otherwise just use a design notes field in jira

Not the whole world uses JIRA, in fact the vast majority of my jobs did not.

"The why" contains lots of information that we don't want to go missing.

Exactly. Preserving the information is important, where it is kept is secondary. I worked both in companies that would rather have this documented as close to the code as possible and companies that would prefer to have it in JIRA or some other external source. Both have advantages and disadvantages.

Thread Thread
 
codingchili profile image
Robin Duda (they/them)

Yep, the most important thing is to document and follow the workflow of documenting design decisions. I mostly use GitHub issues anyways. :)

Collapse
 
anandrmedia profile image
Anand S

"Comments introduce ambiguity and can be misleading as well as increase maintenance costs." - True.

Collapse
 
andre57 profile image
Andre Du Plessis

It is true, yes. But Only when the dev is not capable of using "strongly typed"/ explicit descriptions when using human languages, properly. That's how ambiguity is created in the first place, in any language.

Just as we need to tell a CPU exactly what to do, we need to be able to practice the same skills to inform humans exactly what we mean.

Now is the time to either thank your school's language teachers, or go back and study more on how to use human languages.

Thread Thread
 
codingchili profile image
Robin Duda (they/them) • Edited on

They introduce ambiguity/mislead when they are out of date with the code. Sometimes the underlying implementations change, sometimes the code is updated but not the comment. Sometimes the comment is wrong in the first place.

Language is of course important, in comments, specifications, design and code. However, the majority of programmers do not comment (or read) in their first language. Even if the comment author has perfect English - we can never guarantee that everyone who will read that comment has. Perfect English isn't bulletproof against misunderstandings either! Programming should not require perfect language skills, we should have better tools and practices. Writing comments that are easy to understand is tightly coupled to writing code that is easy to understand, and easy to understand code rarely need comments.

On a final note we, the people need a single language to unite us. Abolish language barriers. Abolish nationalists.

Thread Thread
 
andre57 profile image
Andre Du Plessis

I understand where you come from, Robin. However, I used the word human language, not English. I agree that hundreds of millions of coders are not all that familiar with English, even though most programming languages use it as a basis.

It has nothing to do with being nationalistic or not. It's about being practical. Language barriers will be with us for at least another 50 years, if not much longer until linguistic AI works 110%. Whether you are a Mandarin, Hungarian, Zulu, or Inuit speaker, use your own language properly to communicate as efficiently in that language as you are trying to do in the programming one. That's my only message.

Thread Thread
 
codingchili profile image
Robin Duda (they/them)

I don't think we should pick the language we are most proficient with. Only 1 in 800 people speak Swedish for example. I'd rather read non-perfect English than any other language I don't understand.

Of course comment quality would be better if everyone just used their first language. Comment quality means nothing if the reader doesn't understand the language.

I think having 5000+ languages is not very practical, having 1 is. There is no reason to keep all these languages around other than cultural (nationalist). We can never know who will read our code in the future, but they likely know English or Mandarin.

Collapse
 
tykok profile image
Tykok Author

Totally, you have to know how to use this tool and be aware of it.

Collapse
 
fjones profile image
FJones

Actually, please don't comment your code (public API notwithstanding). Write code that is either easily testable (or even the tests themselves!), and easily replacable.

I don't need to read your novelization of what your code does. I need to be able to rewrite it in a fashion that I understand, or make changes in the right place.

The only code that needs comments is code that makes no sense at face value.

Why are we serializing an object just to deserialize it immediately? Oh, the ORM we're using introduces an unstable child object and this was the easiest way to ensure it was transformed into something sensible at this point? Okay, makes no sense, but I probably shouldn't mess with that.

Collapse
 
angelbt91 profile image
Ángel Blanco

+1. I get the idea behind author's post, but usually comments are kinda annoying to me. Either because the code is already self-explanatory and the comments are redundant, or because the code could be refactored to be clearer instead of having to explain it through comments.

Collapse
 
tykok profile image
Tykok Author

I don't totally agree with this view, and I fully understand everyone's different points of view on this sensitive issue.

Nevertheless, if we assume that the code is explicit enough. Then it would be easy to code for everybody, and we have to keep some reference points that will help anybody to understand our code (*nobody *codes without a minimum of reference points).

Besides, the idea is not to make a "novel" but to describe quickly in one line the final goal of the few lines written. And as I said quickly, I don't want to write constantly but use this tool properly to make the reading more pleasant for everyone.

Collapse
 
thenickest profile image
TheNickest

You mention β€žreadable codeβ€œ produced by comments. I would say if you need comments to make your code readable, it isn’t exactly this in the first place. You have unreadable code.
I would always aim at readable code and comment only spots where they help reducing time to go through a complex peace of it. If for whatever reason your code must be in a form where humans cannot understand it, tell me what went wrong in the first place?

Collapse
 
tykok profile image
Tykok Author

What is a readable code, and what is an unreadable code?

Always the same problem, a code that is readable for one may not be readable for another. There is no such thing as code that everyone will understand because we have deduced that it is readable.

Another thing : a "readable" code written 2 years ago will probably not be readable today...

The goal is as I said to have reference points allowing everyone to find their way.

Of course, we should not generalize and use this tool sparingly. But knowing how to use this tool is a real asset for everyone.

Collapse
 
thenickest profile image
TheNickest

I cannot agree on that. Let’s take the English language as a common way to understand code. Anyone who can read English, can read code consisting of English words. So why not use actual words. Only cut words where necessary or form abbreviations if it cannot be avoided. I would claim this brings us pretty close to everyone understanding it. Of course, an hour, week later I might choose a better name. But at that very point in time it was my best take. So maybe 2 years later I might be like β€œyeah, that could be named better” but not necessarily not understanding it at all.

Thread Thread
 
tykok profile image
Tykok Author

If you stick to a personal code why not.

Use abbreviations for you: ok. But to assume that EVERYONE will understand you is utopian.

You just have to realize that you are not alone, that some will understand more easily than others. That this tool exists, and that it is necessary to use it as it is necessary.

Thread Thread
 
thenickest profile image
TheNickest

But the fact that one cannot please EVERYONE does not mean that I should not write human readable code where applicable. And you are right - realise that you’re not alone. Stop writing code only you understand or a small elite group. Make it accessible to the majority. At least to EVERYONE able to read English.

Collapse
 
aileenr profile image
Aileen Rae

This reminded me of a fantastic talk called The Art of Code Comments. The main philosophy is to use code comments for the "why", not the "how". It gives some really nice examples.

Collapse
 
tykok profile image
Tykok Author

That's really interesting, thank you for that !

Collapse
 
incrementis profile image
Akin C.

Hello Tykok,

thank you for your article.
I like the general mentality of commenting code when commenting helps.
I imagine that "when it helps" is an issue in and of itself, since it allows bad code to go uncommented.

🌚 Friends don't let friends browse without dark mode.

Sorry, it's true.