
Writing system software: code comments - ssklash
http://antirez.com/news/124
======
Supermancho
> Finally backup comments are the ones where the developer comments older
> versions of some code block or even a whole function, because she or he is
> insecure about the change that was operated in the new one. What is puzzling
> is that this still happens now that we have Git.

It's not puzzling _at all_. The implications of choices (which aren't limited
to small blocks of idempotent code) are not a matter of reading through the
history and figuring out "hey right HERE it could have been done differently".

There are many points where the strategy or specific implementation (due to
the flux of integrations with ever-changing dependencies) have had relevant
implementations and dead-ends, which serve as a teaching tool. The surrounding
code often looks strange and wasteful, until you see the comment showing what
USED to be there 20 commits ago.

There's also the planned commit, which is one where a functional bit of code
is done and a dependency isn't ready before handoff to another team or
developer. Ever had to wait for months for an integration? It happens all the
time. Putting a specific integration in another branch you have access to,
that may not be accessible for internal procedure reasons to someone else,
leaves a developer with an obvious path forward to salvage the work - put it
in the code commented out with a little teaching.

How many times do you make a change and it goes to prod without tests? Happens
all the time. Those kinds of places don't always have typical branch hygiene.

You can label these different kinds of comments different things, but they are
usually to these esoteric ends rather than "just for nostalgic 'membering".

------
lioeters
Prior discussion:
[https://news.ycombinator.com/item?id=18157047](https://news.ycombinator.com/item?id=18157047)
(2018)

------
tester756
Handy article when arguing with "clean coders"* about comments

* people who claim that UB's against them due to misunderstanding(?) his book/tweets(?), dunno.

Anyway the need for those discussions is an indicator of how this industry
hasn't matured yet

