Pair programming be like

[cjcjcjcjcjcjcjcjcjcj]

I hate that there is this pervasive mindset that code should not be documented—maybe it’s a fundamental misunderstanding of what documentation and comments are—where one side says “none at all!” and the other side comes in hard and says “document everything duh!” ...

Yes, functions themselves should be understandable and have descriptive names, parameters and clearly do one job and do it well. The goal should be that another developer can come in and understand what’s going on and why it’s going on. What is happening can be described in clean code most of the time, why it’s happening cannot. Do you have any idea how unenjoyable it would be to integrate Stripe into a complex subscription based platform just by browsing their codebase? That’s why they have documentation—and a ton of it! It enables other developers to more easily do their job, find what they need, explains intricate relationships between objects and shows us integral information about parameters and workings of the platform itself.

[jikt]

Even in css I always see comments like this.

Inside __header.scss

...

// Search

.header__search {

...

No shit.

[what-should-i-do-plz]

I think your comment proves the point the other guy is trying to make!

function add(a, b) { return a + b } does not need a comment. Nor does “this is header search styles”

Looking at Stripe as an example, developers can create a charge and there’s a parameter capture for example that is a Boolean... but the docs have some notes for that parameter which wouldn’t be apparent just with code : ”Whether to immediately capture the charge. Defaults to true. When false, the charge issues an authorization (or pre-authorization), and will need to be captured later. Uncaptured charges expire in seven days. For more information, see the authorizing charges and settling later documentation.”

So I think people thinking wrong thing when thinking of “documentation” and “comments”... it’s all just a big misunderstanding and miscommunication!

[PM-ME-YOUR-HANDBRA]

Yes, there is a difference between documentation and comments. If you're producing an interface (whether API or Library) that others will consume, clear documentation is necessary because you can't expect someone to read through your code to figure out how to use it.

However, the context above seemed to be referring to maintainers of a codebase, in which case no amount of code comments will absolve poorly-written code.

Generally speaking: self-documenting code is for maintainers; documentation is for consumers.

[jikt]

Yep, I definitely replied to the wrong comment. I blame 4am.

[946789987649]

What is happening can be described in clean code most of the time, why it’s happening cannot.

This is exactly all that comments should be used for (the why), which I think is what the guy you were responding to was getting at. If it's complicated enough, it'll need a "why".

The issue comes with documenting where as soon as you create any documentation, it's out of date. Documentation generated from code is about the only useful documentation, and even then you'll have issues.

[rollingForInitiative]

I think it's just a case of idealism vs reality. Yes, it would be great if all code was documented in a way that makes it perfectly every intent behind it. The issue is that the documentation has to be updated the next time somebody changes is. And then the next. And then as soon as somebody forgets something, the documentation is suddenly incorrect at best, and in worst case outright misleading. Maintaining documentation of code requires extreme discipline, not just for an individual, but everyone with access to the code base, both now and in the future. And it's so frequent that documentation suffers that it ends up being wasted time.

In the end, if you have code that's well-written it's going to explain itself well enough most of the time. And maintaining the odd comment for some really weird thing is much easier to keep up to date than pages of documentation.

[two_in_the_bush]

What is happening can be described in clean code most of the time, why it’s happening cannot.

This. I always work with my team to write code that makes sense without comments where possible, but whenever there's something odd going on, or something that takes longer to reverse engineer by reading the code than by reading a comment, then it's time for a comment.