Don't Write Comments

Why you shouldn't write comments in your code (write documentation)

References:

[arkadiusl]

There are two sides of this, either readable code with minimal comments or unreadable code with lots of comments. I think it's best to combine both approaches: unreadable code with minimal comments.

[realroadrunnr]

I find the general rule "comment WHY you're doing something, not WHAT you're doing" is a good rule of thumb. Ideally the code should speak for itself but sometimes reality or co-workers get in the way of that ;-)

[truthmatters]

There are 3 types of comments. Comments that tell you:
- how the code works
- how to use the code (aka documentation)
- why this design was chosen after mapping out the problem domain

Only the first one can be mostly made obsolete by readable code.

[Returnality]

Okay, that's cool and all, but writing assembly without comments is suicidal.

[petabyt]

Good luck maintaining a 400 line assembly file with no comments.

[LeFrog]

"Do you guys find yourselves reading comments to understand code?"

I work in numerical analysis, and most of the code I read is written by mathematicians. There are no comments and the variable names are often obtuse. So when reading someone else's code, I simply add comments, because it's easier than modifying everything... I try to follow your good principles for my own code, though!

[beclops]

I like this philosophy but people should be careful in practice assuming their code is self documenting to all. New devs/new hires may have a different threshold for this and I find that some higher level devs use the term “self-documenting code” to write complex and comment-less code with their egos while losing the practical point of it entirely. Either way I agree that documentation > commenting and writing self explanatory code should trump a comment (since many times they can be a code smell in its own way signifying over complexity).

[davidg]

I like everything about this in theory, but not in practice.
For an ace dev team whose members are all on the same page, this advice could really streamline things. Unfortunately, not all coders are at that level, or on the same page. And even if you've assembled a dream team to work with, it's not going to last forever.
Basically, what I'm saying is that you have to remember that you're dealing with humans.

That said, there are certainly more intelligent ways to write comments and documentation. It's better to explain why a line/block/etc. exists than what it does.

[yapdog]

No matter how well the code is written, comments are useful. It has to do with the fact that comments are rendered in a separate style which makes them easier to visually separate from code. So, the way I write comments is generally concise (i.e. single line) and right justified. I'm able to easily understand my code as a sequence of stages without reading through each function, enum, variable.

[birdlegscass]

by far the purpose I use comments most for is as short headers to label sections of code. stuff like "jump" "collision" "take damage" etc. it makes my code so much more navigable, both for myself and others

[MinefighterLP]

I always code and comment with the philosophy "Will i understand on a glance what this part does after a couple of months?". If you haven't touched a particular project in a while, its great to have good comments AND self explaining code (and a good documentation). Sure, things might be self explanatory while you write them, but it might not be for someone else reading/maintaining the code.

Also, i have quite a bad memory, i quickly forget why i did things a certain way, so having detailed comments is quite practical.

[FrancoSciaraffia]

I mostly write comments for future me in case I need to come back to a complex system after several months or even years. I find it's easier to grasp the context and intention of the code through a series of comment rather than just trying to understand what the code is actually doing. At the end both are necessary. But without the comments I would have to spend a lot more time trying to understand why/how I did things the way I did.

[TonyHammitt]

I worked at a very small company where the code base was strangely devoid of comments. Just a reference at the top as to when the code as "cleaned up". Turns out that the guy who "cleaned up" the code was at one time the only programmer working at the company. He actually deleted all of the comments from the code and left that note as to where in the version history to look to see where the comments were, as a form of job security. He was the only one who knew how to find the documentation, so he could pull miracles out of his butt. Eventually I fired him for other reasons, but in converting the old code repository to a new system, I found the old documentation. Wish I could have re-fired him.

[garrettgutierrez]

I feel like all the advice from this channel is tailored for a perfect world. Yes, in a perfect world, code is written in such a way that it is totally readable, and so we don't need comments. But in the real world, you are going to right code that you know isn't very readable, or you are going to wrtie a line of code that, when someone else maintaining the code revisits it, they are not going to know why you are doing the thing you are doing or the way you are doing it. So in the real world you are going to run into a lot of situations where comments are totally appropriate.

I have many of my own private git repos that even when I, the person who wrote the code, revisits them, I am not sure why I wrote it the way I wrote it. A small amount of comments every so often are going to be absolutely appropriate for any coder's toolset be they beginner or pro.

[Peter_]

There is something very satisfying about picking descriptive variable names, so that the variables themselves serve as "comments".

[John_L]

I think it's dangerous advice to simply say "Don't Write Comments". Of course it is a good thing to equate constants, correctly type cast and use meaningful names for variables, procedures, functions, etc. That can significantly reduce the amount of commenting required to make the code understandable to others and/or to your future self. But anything other than the simplest code benefits from comments that explains the context and reason for doing something a particular way. Comments can also help those that come after you to understand coding tricks whose operation might not immediately be apparent but which are, for example, resource efficient - especially important for real-time applications. Having written code in a safety critical real time environment, sensible and considerate commenting is in my opinion essential.

[WalterWoshid]

I understand why you feel this way, but before I was really good at what I was doing, I was heavily relying on comments. And I think that's the important thing, whenever you want people to possibly participate, in an open-source project for example, you want them to understand you and your idea. Especially because there are many beginners and sometimes before they can read code fluently, they want to understand what's happening there, especially for a complex project.

[TheSpacecraftX]

Good self self-commenting code can tell you what is being done. Not why it's being done. The WHY is the most important thing to comment. I've started 2 jobs in the last 2 years (and helped onboard people at both) and I can tell you it's a lot easier to make sense of existing code and use of unfamiliar libraries when there is a comment to explain why something has been done. Job 1 had must more extensive and versioned docs, job 2 had way better code standardisation and comments (with better code review). Job 2 has been much more pleasant. Sometimes I find strict commenting standards to be excessive but the lived reality is that sometimes having too many comments is better than definitely not having them where they should be. Doesn't help that both involved working with mathematicians, who are really bad at code readability on their first few attempts because they like to write code like maths and both don't use good names, and their documentation can get highly mathematically technical and hard to relate to the code.

[lordkekz]

I largely agree that more readble code is generally preferable to unreadable code with comments. But I do think that especially in large functions where there are several "paragraphs" or steps being executed, short comments are useful to act as a sort of heading to more quickly orient oneself inside the function. Of course, it may be possible to split the function into several parts, but that can actually make it more obtuse (and more fragmented to read) if the steps don't make sense out of the context of the larger function.

[pafnutiytheartist]

I like this approach: the code should tell you what it does, the comments should tell you why it's doing that.