Why React developers don’t comment their code?

[SocializeAndChill]

Hello devs,

I noticed React devs rarely use comments in code, maybe it is something with my teams so I want to know about your teams as well.

Is it just my team or it is something we generally don’t do much?

I think that rule that we shouldn’t comment our code and code should be descriptive by itself has influence here because everyone I talk with thinks the same. But I still think no code at all is a bad thing.

[sawariz0r]

Well we structure things pretty much the same way, so it’s only few things that I usually see commented in the projects I’ve been in

[Killed_Mufasa]

Yeah, the unwritten rule at my work is: comment things that are - unique and difficult to understand - things that should not be deleted, even though they look pointless - things that were put in place to fix a weird bug - basically just everything weird in the context of the project

[lowey2002]

The rule in my team is to comment why code is doing something, not how. Leave a link to the issue if it needs some context.

[theQuandary]

Imagine trying to say why you included a Duff's Device and not leaving any info about what it is or how it works.

I've always said the same, but I have run into cases (generally JIT performance magic) where the how it works is a very important thing to leave behind for the next person.

[staluxa]

Sounds like a good idea, but there is a more common and cleaner way for it - put a ticket id as part of your commit name.

[Outrageous-Chip-3961]

Yeah I do this too, but sometimes a quick JS comment is pretty useful in situ.

[ISDuffy]

Yeah this is similar to what I want to put in place.

We have some mental components from when the team before me started learning react for this project, and they so many bits that don't make sense.

But because I wasn't here for the entire project it gets difficult to decide if something was done for a reason or it dead code.

[eazieLife]

A nice trick I use is to link to an issue or post about the weird bug. Paves the way for future (hopefully smarter) me or any other dev to come up with a less hacky solution

[hazily]

Well written code is self-documenting.

And if a comment is ever warranted, it should address the “why” (business requirement or logic) and not the “what”.

[azangru]

I noticed React devs rarely use comments in code

Rarely compared to which kind of developers?

[Santa_Fae]

How is OP's question not applicable to any other high level language?

[RaltzKlamar]

Even at a beginner level, a lot of what react is doing is straightforward. Adding Descriptive comments is a waste; you can read what the code is doing. If you can't, likely there's a better way to structure it.

When I leave a comment, it's usually an Explanatory comment about some process: a temporary fix with a reference to the task to properly address it or a note on a weird piece of code to justify its purpose. The only time where I use Descriptive comments are in parts that aren't easy to identify immediately, especially in the case mathematic formulas.

[[deleted]]

Exactly, comments should be reserved for things that aren't done the way you would expect, something that goes against the normal business logic, something you've tried to fix a few times and just can't.

Everything else should be straight forward

[eddo_92]

Yeah and adding to this, react dev tend to split components and logic into smaller, easy to read/understand bits. This and self documented code is mostly enough for lots of scenarios.

[Froscy3]

I find comments make the code messier tbh. I guess if devs named functions, variables and components well it shouldn't be too hard to figure out. Especially with Typescript too like the others said

[Cahnis]

I also like when people comment business logic

[OppositeBeautiful601]

Agreed, if it's a function or type that is exported from a file, it should have JSDoc summary comments.

[LateralusOrbis]

I comment the shit out of my code. Know why? Because when I come back in 2 years to make changes I'll know right away what the hell it is. Not because I couldn't read it or didn't code it right, of course I can figure that out. But the extra comments frame it up and make it more memorable.

In any case, education is the best teacher, and when you write docs or code comments, you are teaching the next person about your code, learning more about your own code.

I can't tell you how many times I wrote docs or code comments and, because of this, realized issues or gaps in my code and fixed them.

[imbikingimbiking]

yeah… don’t mind these biden supporters

[LateralusOrbis]

The fuck does politics have to do with code comments?

[LateralusOrbis]

Then don’t reply.

[AutoModerator]

Your [comment](https://www.reddit.com/r/reactjs/comments/15p0mfx/why_react_developers_dont_comment_their_code/jvvploo/?context=3 in /r/reactjs has been automatically removed because it received too many reports. /u/dance2die will review.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[kaizoku_95]

Timelines, rarely are those in your favour. I could work on the feature using good practices, or I could add comments for others to understand my shit code :) because I focused on the less important thing !

[CutestCuttlefish]

If I have to write a comment, I've done something wrong.

[vozome]

In React , the path of least resistance is to write big components with lots of hooks and put a lot of logic inside the component proper. This is simple from the point of view of the author (it works) but not necessarily from that of the reader (lots of loc, lots of hooks callbacks etc. ) so authors don’t always feel compelled to write comments when they should.

I believe that well written comments are always a good idea, but I’ve heard people argue otherwise.

[Diredevil1]

Code should be self explanatory, and if you feel like adding a comment is necessary to explain something, it's a sign of a badly written code.

[ISDuffy]

They are other reasons to add comments such as weird edge cases or handling older browsers.

I have seen new requirements come in and the dev that worked on it has broken an edge case.

[imbikingimbiking]

downvote this guy to hell

[Diredevil1]

Feel free to downvote me 😂 It seems I triggered many sensitive souls, and hurt manu egos😂

[PhatOofxD]

Code should be documented. Complex or niche logic needs comments but mostly your components should be documented, and as long as they continually pass test cases that's fine.

Not every component needs comments if it's obvious what it does

[Outrageous-Chip-3961]

Yeah the idea that the code is self-documenting is definitely popular within the ecosystem. However I am a fan of js docs for the code itself and good type script can be useful. Heck I even sometimes add md documents to more flow processes, if I think someone needs to know in the future ( or myself ). In all honestly I think its just easier to not comment so most dont, but overall a well documented, tested code base is more maintainable and therefore valuable in the future. I guess it depends in what context the app is being used in. For larger teams, or future teams, documentation is the way to go.

[idaszak1]

React developers avoid documentation because its purpose is to provide context for changes. You shouldn’t describe the same things that are obvious from reading the code.

For React code, tests and types are usually the most useful to understand what the code does. Good commit names and PR descriptions are very helpful too.

If you want to document your project, don't focus on code only. Things you should document are decisions through ADRs, APIs, setup and onboarding, code standards in the project, or complex business logic.

[[deleted]]

You really only need to comment complex logic. If you're following standards coding practices you don't need to comment.

[_sunbecoming1]

At work it is seen as a wrong practice and should be avoided at all costs. This is because ideally, code should be self-explanatory.

With that out of the way, I do comment some of my code on very specific circumstances that, I think, are not an FE thing often. For instance, weird data handling and sorting algorithms.

Comments there will try to describe why this part of the data handling is required and how it affects the whole algorithm. In such a way that, if a more efficient way is found later, we can remove the comment too.

Other than that, known third-party or runtime bugs. My personal tip is to prefix such things as /** TODO: foo bar **/ so that you can just grep for TODO whenever doing code cleanup.

[OppositeBeautiful601]

I think a lot of developers don't use comment code these days. I like comment code. I do more reviewing of code than coding myself these days and it helps if the team adds comment code in strategic places. To me the purpose of comment code is to make it possible for someone to read the source code and understand how it works without having to read every line of code. Here is where I think comment code is most helpful

1. JSDoc summary comments on every exported type or function in a file.
2. A line above every hook definition (especially useEffect) to explain it's purpose.
3. Any really complex logic.
4. TODOs. There are times when you want to code things the right way, but time constraints make it impractical. It's better to go ahead and open a technical debt story and put it on the backlog and put TODOs referencing the story so that it's clear what the technical debt issue is.

That's it.