4 ms·

I use a lot of comments during development, but rarely keep them around in final production code. As features become stable, I tend to subconsciously delete the

I use a lot of comments during development, but rarely keep them around in final production code. As features become stable, I tend to subconsciously delete them in the underlying areas. My rationalization is that source control has already captured this history, and if someone really wanted to see what I was thinking, they could review the commit(s) for that file and get a perfect picture. There are some places where I think comments should persist, such as where you expect future developers (yourself) will be breaking ground again for additional features. Things like "TODO: New Components go here" on a switch statement, or "Review the following issue # for change process around this type" located at the top of a very important piece of code.

latency-guy2 2y ago
> My rationalization is that source control has already captured this history, and if someone really wanted to see what I was thinking, they could review the commit(s) for that file and get a perfect picture. I used to think this way too... and I still kind of do if things were under control by me. Unfortunately many times things are not under control by me. You have no guarantee your commit history will be maintained. I don't mean this as in someone is going to do something silly and edit your commit history. I mean this as in people will move your repo. Multiple times. In these multiple repo moves, people will absolutely perform an 'initial commit' on your 25 year old SVN/Mercurial/etc. repo into the new location. Even worse are the ones that go private git repo to public git repo where this is basically the minimum expectation. All those tools that help us migrate from one versioning tool to the next be damned. Some clever folks even plan for this as their earning potential and end up as extended contractors well into their twilight years. I don't fault them for their plan, but can't say I love them either. I won't say their expertise is not needed, it absolutely was/is, but it wasn't their code that represented their expertise. You have to inherently have some trust in your successors that things will always be the way they are, and that the plan will always work the way it ought to with the right decisions being made the entire way. From my experience, it doesn't matter how smart or capable or predecessors or successors will be, it may not even matter when it comes to yourself. The short, fast, least mentally taxing route is the route that is taken and becomes de facto the best route.

latency-guy2 2y ago

> My rationalization is that source control has already captured this history, and if someone really wanted to see what I was thinking, they could review the commit(s) for that file and get a perfect picture. I used to think this way too... and I still kind of do if things were under control by me. Unfortunately many times things are not under control by me. You have no guarantee your commit history will be maintained. I don't mean this as in someone is going to do something silly and edit your commit history. I mean this as in people will move your repo. Multiple times. In these multiple repo moves, people will absolutely perform an 'initial commit' on your 25 year old SVN/Mercurial/etc. repo into the new location. Even worse are the ones that go private git repo to public git repo where this is basically the minimum expectation. All those tools that help us migrate from one versioning tool to the next be damned. Some clever folks even plan for this as their earning potential and end up as extended contractors well into their twilight years. I don't fault them for their plan, but can't say I love them either. I won't say their expertise is not needed, it absolutely was/is, but it wasn't their code that represented their expertise. You have to inherently have some trust in your successors that things will always be the way they are, and that the plan will always work the way it ought to with the right decisions being made the entire way. From my experience, it doesn't matter how smart or capable or predecessors or successors will be, it may not even matter when it comes to yourself. The short, fast, least mentally taxing route is the route that is taken and becomes de facto the best route.