Had a PR blocked yesterday. Oh god, have I introduced a memory leak? Have I not added unit tests? Is there a bug? What horrible thing have I unknowingly done?

... added comments to some code.

Yep apparently “our code needs to be readable without comments, please remove them”.

Time to move on, no signs of intelligent life here.

Tell the person who rejected your pr to go fuck a donkey. How stupid are people (or companies) these days?

I'w with the one who blocked your PR. Comments are a catalyst for code rot.

Exhibit A:

@netikras I agree, comments can contribute to that and your example is horrible, but the problem lies not in comments themselves and categorically denying them is wrong.

@netikras it seems that either the comment was misleading from the start or someone updated the code and forgot to update comment as well.

@zemaitis Exactly. And this happens all the time. You might comment some class or a lib API method at high level explaining what and how it does. But over the time the inner workings of that lib will change and the comment will no longer be correct. It is impossible to chase down and correct all the comments every time you make a change.

And this, boys and girls, is why code comments is a bad thing. Writing a comment is admitting that you have failed as a developer, as R.C.Martin would say :)

@netikras but uncle Bob also says that it is sometimes unavoidable to use comments.

@netikras comments should explain why you've done that and only in very rare cases what/how.

@TobyAsE yes, in very speciffic cases. And it's still better w/o them.

@irene And I believe that's exactly why the PR was denied :) To prevent comment-reality dissonance in the future and avoid mistakes. Do reviewers track every single code comment linked to every single LOC so they could effectively know which comments turned wrong after bugfix? I don't think so

That's fucking bullshit!

I am a senior dev with decades of experience, and just yesterday, the very fact that I *do* comment my code, saved my sorry ass _twice_!

Without me having commented these two sections two years ago when I originally wrote the program I was working on, I'd had to go through many tedious hours of research. And I am one of those freaks who spend (too much) extra time to write extra beautifully formatted and readable code. (astyle helps a lot, though)

Tell those nutters to go and fuck themselves with an extra big pineapple! 🤬

@netikras I would still agree to keep comments in unit tests. Unit tests should be the best documentation.

@irene Still too messy. Have you done code reviews in large projects? How do you know which comments might need changes if you add another value to some ENUM? Even worse if you product is relied on by other internal apps -- how will you know which comments in those apps have you just made incorrect?

There're just too many points of failure. If it's possible to not write a comment it's always better to not to write a comment.

@zemaitis That would mean that you first have to find a relevant (if any) unit test for the section of code you are investigating. This can get quite time consuming if the area consist of many function calls that are all individually unit tested.

And then you have the problem that the unit test can only document the test according to the meaning of the function you test. But what a bout the situation and the circumstances, and maybe the reason of the exact workflow at the place you are really looking at?

What about the usage of functions from some library which has its own unit tests, but is held by a different apartment?

The API must be directly documented and not hidden away.

Instead of complaining, try to understand why your PR was blocked.

Peer reviews are one of the best tools of self improvement, I'm always excited when I get comments from my colleagues on my PRs, even for minor fuck ups.

The reviewer who blocked your PR was 100% on point, it's always better to write self documenting code, instead of relying on comments.

Remember - only code tells the truth. Words can be misleading.

And why would anyone also want to maintain the comments anyhow?

@netikras If you change your API, you have to update your API documentation and inform all consumers of the library/framework/toolkit/whatever whose API you just changed.

If you add something to an enum, you know already where that change is relevant, or you wouldn't have added the key anyway.

You can say what you want. Nothing justifies not writing smart comments and API documentation.

No, nothing.

And no, that a comment might get invalid due to some code change is not relevant. You either know the code and the commentary, or you are in the wrong place. So make yourself familiar with the code *beyond* what you are working on, and everything _should_ be fine.

Do have any idea how many times commits in larger projects only concern comments and documentation? Many! And for good reason.

People saying they have no time for that, will pay thrice the time later.

Nothing justifies not writing smart comments and API documentation.

No, nothing.

@netikras I know there is a risk that comments can be outdated and I also think there needs to be more of a "clever" use of comments.

Exhibit A:
// Saves the user data
func saveUserData()

Is ridiculously unnecessary, and have had to stop that in the past. Don't comment for comment sake.

But to deny all comments saying that the code must always be readable, nope gonna disagree with that. In my case we had business logic, that needed to be the way it was because of a decision by backend / Product. Its not immediately obvious why that code is there, can't be moved without re-architecting the entire app and very few other options for the way of writing it. At least 1 dev has made a mistake with it already. In this case we need to add a comment more so to explain why, rather than how. Removing this comment is actively bringing confusion into the project and adding no benefit

@ObiSwagKenobi Yes and no.

Code should always be as self-explaining as possible, agreed.

But no code, not in a million years, can explain why something is done in the way and/or order that is exactly used right there, or what consequences are in place on some not-so-obvious or external data structures.

I do not say you should comment what you are doing like rewriting the code in pseudo. That would be very bad commentary anyway.

But background information and *why* you do exactly _that_ right _there_ will save you a ton of time later.

@netikras Stop exaggerating the problem. What you did is you created an endless loop.

According to you code needs to be so perfect that you wouldnt need any comments.

What if you spend whole day just to figure out what some feature is doing?

Then you will claim the code was not perfect?

When I joined a startup 6 months ago I had to work on android app so first month I spent investigating why certain decisions were made. There were are almost no comments. Firebase and gcm services scatterred between 5 company emails which are unused. In the end my conclusion was that previous 2 devs were fucking lazy pieces of shit who just wanted to play around with newest buzzword libs. Thats it.

Reality is that the very same code can be viewed by developers from different backgrounds, different experience levels and different levels of understanding the business logic. There needs to be comments. Otherwise you allow lazy devs doing whatever they want while claiming that its clean coding

@practiseSafeHex @zemaitis You two have great points. 👍

If I were so arrogant to assume that my code was so perfectly written that it all was intuitively understandable, I would neither let my apprentice nor my students have a go at it.

...they might make a blotch on the carpet...

I'm not denying _ALL_ comments. I'm just saying comments should be avoided whereever possible. Replace them with expressive variable/class/method names, apply design patterns making your code cleaner and clearer, write SOLID code to make your structures and algos do only one thing and do it well, effectively eradicating the need to explain that your algo does this, that and that other thing as well.

I was a new guy on a project a few times. Misleading comments caused my mistakes that were later pushed to PROD (after reviews, yeah). Some comments were just nonsense whish I was tempted to investigate and waste my time on.

Prolly the only place I enjoy finding comments in is class interfaces (in java) (or headers in C++). Still they should be as short as 2 sentences max.

Remove the comments... remove... the... fucking.. comments... What?!

My 2 cents here. Comments as much as everything around our work as well are tools in our toolbox to help us get shit done. Their value needs to be put in perspective to the project and people working in. Debating the usefuleness of a tool (comments here) is therefore futile on this platform and would be a topic for a open talk in a forum(e.g Value of commenting code vs. Debt of documentation in Agile Environments). We also need to remind us that devrant itself is also to rant so I can understand OPs reaction. To turn this into more usefulness I´d advise to confront the PR and understand why this rule has been put in place. Thats how I discover new ways of thinking about stuff I would never think about.

Some Uncle Bob fanboys really fucking piss me off, I tell ya.

@netikras When changes in your code base influence so many parts that you can't update all related comments. You have a much bigger problem. Unpredictable side effects are a sign of bad architecture.
I wouldn't consider this a valid argument against commenting.

Comment the why, not the how.
Code explains the how.

I'd reject any PR lacking needed why comments.

Comments don't explain the code to you, code explains the comments to your computer.

@CoolSonu39 😅

I'm not really a senior or smth, but I think the most important part is to avoid making "dependencies" inside a comment. For example:

void a() { b(); }
/* b is called when a is called */
void b() { }
void c() {
/* We need to do smth
because b does not do it */
doSmth();
b();
}

I think these kind of comments can backfire easily.

I think that writing comments, which only describe inner workings of a function is safe. When functionallity changes, it's hard to forget updating them.

If you are unintentionally making dependencies, you basically have to check all over the place, when a single function changes.

It bugs me how many people still think comments are to explain what a block of code is doing.

No, only rarely will a piece of logic be so complicated that it will need a comment to explain what it is doing, and if you find yourself in a situation where that is necessary, it’s a good indicator you might want to rethink it.

Comments should explain WHY something is being done. No fancy variable names are going to be able to explain something that is only apparent when considering logic from elsewhere.

Good architecture can reduce this, but sooner or later you will need to explain why something is being done because there’s logically no way to infer it just from the given code.

That’s why you use comments: to save the developer from having to waste time solving a mystery when it could be clearly communicated in a sentence fragment.

It’s absolutely ludicrous to ban comments entirely, if you care about having a stable and maintainable codebase.

@CoolSonu39 one more:

"comments don't run"

Removing the comment doesn't magically make code readable without it.

Ok thanks everyone for the tonnes of input. I think I get what you are all saying.Its taken me a little while to read all the comments and understand the points and the motivation.

To summarise the outcome, next time I have an issue with PR's or code comments ... don't discuss it on devrant. Lesson learned ;-)

Always comment, always and always. Idk who has come up with this retarded idea that the code should be readable, self-explanatory and therefore need no comments?

One of the easiest and most beautiful codes I've read are with comments.

Comments provide clarity and understanding of what pieces of code do.

Just because you think the code you write is easy to understand, does not necessarily mean others do.

Each person may interpret it differently, be aware of that.

@irene by someone yes it can.

@irene You are right, of course. But you forget to add complexity. If the number of values manipulated by a certain piece of code, with those values come from many different places, only reading the code can become quite time consuming.

A few lines of well chosen words can save many hours of tedious research.

If you ever get into more complex topics like physics, ray-tracing or rendering engines, you might start to understand.

* If you have an algorithm doing complex math, it is very helpful to write down the mathematical way as a comment. You can backcheck the code then without "decrypting" it everytime you look at it.

Example: https://tinyurl.com/yandas2b (Would you understand line 295 instantly without the comments above?) or https://tinyurl.com/y9mx8c86

* If you have very long and/or complex functions, a "flow plan" might come in handy.

Example: https://tinyurl.com/yc8jpsra

* Another example would be to structure and caption long code parts.

@irene Exactly! 😎

@netikras @practiseSafeHex you actually are telling the truth (that the former did block the PR of latter) or just joking?

@gitlog I did not block his pr. It was an example of why commenrs should be avoided from one of the projects I'm working on. I don't know the OP

@netikras here here!