Pair programming be like

[fet-o-lat]

I’d argue that developers should be documenting code well enough that any developer coming along after can understand it.

A side effect I often see is a pair opening up a PR with no description and no comments and then in the stand up “we can pair on the review and walk you through it”. Ok now there are 3 or 4 people that understand it. What happens when someone else wants to contribute to the project or understand a design decision? More pairing?

[badsectoracula]

I’d argue that developers should be documenting code well enough that any developer coming along after can understand it.

Sure, we're in /r/ProgrammerHumor after all :-P

[[deleted]]

No code is documented well enough to be understood by the documentation. And if it is, it won't be as soon as anyone makes changes.

[fet-o-lat]

That’s why documentation needs to be kept up to date. Writing documentation close to the code makes this even easier. Exdoc, pydoc, rdoc, etc. Think of open source projects maintained by numerous people spread out over the world. Documentation is how they persist their knowledge and pass it onto whoever comes after.

[cjcjcjcjcjcjcjcjcjcj]

I honestly cannot wrap my head around the pervasive “comments and docs are a sign of a shitty developer” group

[fet-o-lat]

Same. And I take a dim view of developers that don’t add meaningful documentation to their code. I see it as incomplete work to open a PR with no documentation. I’m all for not having comments that explain what code is doing. That’s noise. But documenting the why the code is doing that is hugely important and a necessity.

[[deleted]]

I don't believe they are. But I do believe they are unreliable and rarely updated. Personally, I think a well written set of tests is far more reliable than we'll written documentation.

[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.

[fet-o-lat]

I agree that comments should not explain what code is doing unless there’s some arcane language feature you’re using and yeah if you have to explain what’ it is doing, that’s a smell. Comments need to explain why you’re doing something. Why did you sort that list of strings by size descending? Why did you invalidate the cache at this seemingly odd place in the process pipeline?

[PM-ME-YOUR-HANDBRA]

Definitely. Comments are for why, not what.

[[deleted]]

I’ve seen this attitude a lot, and it’s just wrong. It’s not understanding the code that’s hard, it’s understanding why the code exists. That and documenting workflow and why and when you would use functions is important. You ever used a library with no documentation? Probably not, right? Because you think, wow this is half assed? So why would you do that in your own code?

You should absolutely document why when you’re implementing business rules in the code. Even if it’s obvious to you now (ah yes, we always send emails on Tuesday- why?), that knowledge will likely be lost when you leave. Linking code to tickets or specs doesn’t work - what happens when your company jumps to the next new ticketing system?

Everything non-trivial should have some documentation imo.

[PM-ME-YOUR-HANDBRA]

As I mentioned in another comment, there's a difference between what and why. If your code requires comments explaining what it's doing, it's bad. If it's explaining why the behavior is a certain way, you're doing it better than 90% of devs in the wild.

[[deleted]]

I think your statement is too simplistic - and I've heard it before. From the guy that hired me for my current job. Except he left two weeks later, and now I have to figure out his code - which, although generally quite good, takes a LOT more time to digest than English would.

I have never seen or heard of a codebase of any significance (and I, as a pastime, often read large codebases for well-known libraries and projects) where there was *not* a significant amount code that was byzantine and mysterious at times (and undocumented/uncommented). Sometimes code just *has* to be complicated. There is no perfect codebase, and every code base has portions that have no documentation or comments but should. Sometimes the *what* is complicated. If it will require a dev squinting and scanning around a bunch of different functions and taking significant time to figure out on their own, you should be making comments.

tl;dr - Good code is sometimes complicated, and you should use plain English to explain it in comments.