Should You Write Comments?

🚨 IMPORTANT:

Use code KYLE for an additional $50

Should you write comments in your code? It may seem like an easy yes since comments are much easier to read than code, but it is surprisingly more complicated then that. Comments actually can cause some significant downsides to your code which are not always obvious, so in this video I will be breaking down when you should use comments and most importantly when you shouldn't use comments.

📚 Materials/References:

🧠 Concepts Covered:

- When to use comments
- Why comments can be bad
- When to not use comments

🌎 Find Me Here:

#Comments #WDS #JavaScript

[newsgroupsusenet]

I've seen a guy who added comment to 80% of his code, it looks like he's going to launch a missile that launches a satellite

[davidringo]

Whether you write comments or not.. will ultimately come down to your employer. I have worked for a couple of companies that only want clean "self-readable" code and no comments anywhere. Other companies want a huge change log comment section on their stored procedures but don't care if there are any comments in front-end code. Yet others want some level of commenting everywhere. Since I pick up a nice paycheck and mostly like the people I work for, I have stopped arguing, now do as they say and then go home to play with my kitty!

[tacowilco]

In large projects with the complex architecture we write comments where the decision making in the code is not obvious. Also I write the comments to validate certain things like intentional fall-through etc :)

[vincentandrieu]

I really like you, but I don't agree here. Even after 12 years of experience, a short, concise comment car lighten the next lines of code way easier and quicker than reading 10 lines of code (that's just plain logic, reading 1 line of text is quicker than reading 10 lines of code). Of course I'm not talking about line-to-line comments like "here we multiply by 2". I'm talking about design level comments that help you take a step back from your code in just a few words.
Last but not least, when working in teams, your argument "comments are useful for beginners but not for veterans" doesn't apply, because even if I'm a veteran that doesn't need comments, there are some beginners in the team. Understanding/debugging some code written by someone else is one of the most difficult things to do. When the author of the code left some comments to explain what was his thought process, I can guarantee you will understand his code 5 times easier and faster.

[JasimGamer]

sometimes i use the comments as reminder

[Bgrosz]

I agree with this general outlook on comments.

If you choose class, function and variable names well and always do a round of refactoring to improve efficiency, readability and to simplify, then at least 90% of code does not require comments.

That said, there are always (in any non trivial application) going to be areas that are complex because they are complex. Go ahead and comment the crap out of those places.

Also, remember that if you are part of a team of programmers, you are commenting for the worst programmer on the team, not yourself. Don't ask if you can quickly read and understand a complicated section of code, but pick the worst programmer and ask yourself if they can quickly read and understand a complicated section of code. Write the comments for them.

[caturviriyananda]

me : "comments are just for the weak"






alse me 2 days later : "wtf i'd wrote?"

[darkpill]

Coders who say you don’t need to comment haven’t worked in the real world long enough or haven’t worked on projects that span 5+ years. You don’t always have time to write pretty understandable code. You get an error at 3am, and you have to fix / re-write something - comments help. “People don’t update comments” is not an argument, because you can say that about anything. can commenting be abused / be unecessary? Absolutely, doesn’t make it a bad practice.

[huthayfa]

I would prefer outdated comments rather than unnecessary variable

[georgechanturidze]

It really depends though. Sometimes extra variables take up extra memory. Long, Descriptive function names can take up file size unless you are transpiling your code. Certain blocks of code will still need comments unless you want to keep splitting your code into ever-increasing number of files. What’s more is that refactoring your code neatly is often not an option if you’re working at a company where you have to move on to your next task. In that case quick comments are valuable so other teammates understand what’s going on. Perhaps they’ll be the ones who will refactor later. While you should not overdo comments, in most cases the problem is that there aren’t enough of them (if any). You know this if you’ve had to deal with other people’s code, as most of us have.

[deansprivatearchive]

Short Answer: No, unless for prefixes like "TODO:" or "FIXME:".

[HenleyBailey]

I generally comment on the intent of the overall code block (if necessary) rather than what it's doing and try to keep it brief and concise for those new to the project. Sometimes it's not obvious what some code is doing or why it's been written in the way it has until you go to re-write it and end up meeting the same issues the first coder did. Eventually, you can end up back in the same place but having wasted time doing it.

A lot of the time the comments are required as the way something has been put together maybe shouldn't have ever been designed or written in the way it has in the first place which is essentially what it seems to come down to a lot of the time.

[harag]

100% agree with you here, comments are 99% pointless within the code. So many times I've seen comments 3 times longer than the line of code which reads "form.refresh();" Why do I need to see a comment that tells me we are going to refresh the form - Arrrhh. It's just bloat and makes anyone else miss the important code. Comments should be put in the XML section above classes as these (c#) are then compiled into documentation. Variables should be named good, functions should be short etc... I highly recommend installing a complex extension and keeping the complex of your code below 10 or even 6.

[dariusdareme]

I do agree to this when it's possible to explain the code, but It's not always enough and then I write a comment.
Personally, comments are always a godsend and ease mental effort.

Also, neither long variable names nor comments affect the speed of the app, considering compilers and minifiers exist. So, I don't mind walltexts of comments. They are also usually colored in gray in editors, and easy to ignore.

[karoshi]

Usually I write comments documenting an API.

Personal favourite, though: customer wanted Clean Code, no comments at all. Assigned staff didn't even know the language, and demanded comments. So I commented everything that's not obvious for non-programmers. Staff didn't know the algos, so didn't even bother reading the code or comments. So I offered a lecture - customer declined. Made a ten minute screen cast, explaining how to use the library. They didn't even watch it. Nobody did. Still complained I hadn't documented anything.
Well ... contract ended, they had prosa, API docs, clean code, ... couldn't do anything else at that point.

Heard from a former colleague, that they still use it, "admire" the style, etc. That one guy kept complaining, though. So be it.

[GoGroomer]

Great thought process behind code commenting. Properly named variables and functions should speak clearly to define their purpose💕 Thanks✨

[labombarde]

I laid gas line in 22 below zero, fought carpenters for pay and punctured my lung with my own hammer falling 30 feet. Funny to see what people find hard... You're a good kid Kyle. Thanks for your vids.

[dejanpecanac]

Sometimes you want to change old code, function but are not sure why was it written this way. Apart from taking care of bugs you mentioned, sometimes it's a lot easier if you see a comment "this part of code does (just) that ...". I would sometimes add: "you can change this value if you need ... more/less of this/that etc." so someone else doesn't have to check and double check what might break and then ends up writting a new function just to leave the old one alone, not to break anything ...

[jntaca]

I comment my hacks to my own code.
Sometimes I don't have enough time to rewrite all code because of a last hour change, so I comment the hack.

[pipertripp]

One thing that I like using comments for is creating an outline. It's a nice way to lay out what you want to do. You then remove the comments when you've connected all the dots.