I was asked to delete my comments before committing
I've worked in IT for 12 years now — as a full-stack developer and lead dev.
Recently I was confronted with a problem I had never faced before in my career: my team members asked me to remove all my comments before committing code.
We discussed this. Some of them believe that the presence of comments in code almost always indicates that the code isn't clear enough on its own, and that this is therefore a sign that it needs to be rewritten so that comments are no longer necessary.
And I get that.
I've read Clean Code. I've adopted some of the principles described in the book. But I've also read A Philosophy of Software Design, and what I read about the concept of deep modules versus shallow modules really resonated with me. That's not the focus of this article, so I won't say more about it — except to note that the debate over the use of comments isn't over in our profession (will it ever be?).
Back to the situation. I explained to my co-workers that I was using a narrative approach when coding, which can be called "comment-driven development". First I put all my comments, modify them, refactor them, then I write the code below the comments.
These comments help me structure my thoughts. They are an extension of my working memory. Working without them is like having part of my cognitive abilities taken away from me. Once they're written, I still use them when reading the code later during evolution: they are my navigation links. My brain is used to this, so it quickly scans through these comments in a function to figure out where I need to make a change or debug.
They listened to me, they tried to understand, but their final decision remained: they want a clean codebase without this kind of comment. In their view, these comments aren't useful, won't be read by the team, and certainly won't be maintained. In a nutshell: no noise.
But for me, those comments weren't noise.
They were how I think!
The only compromise they came up with was to delete my comments before committing. That solution didn't sit well with me. It was too frustrating and would result in too much wasted mental energy down the line. At the same time, I need to be pragmatic and respect the team's decision.
Go deeper into the problem: the issue is not the comments themselves
Git doesn't distinguish thinking from sharing.
Git doesn't distinguish between:
- code I write to think
- code I share to collaborate
So if I follow my co-workers' rule, every time I want to commit, I have to clean everything up.
Remove my comments.
Polish the code.
Make it "presentable".
And for some of that it's fine… until I realize what that means for my way of thinking and coding.
Deleting the comments was deleting my thinking
Every time I committed, I would delete:
- my navigation links
- my reasoning
- my half-formed ideas
- my doubts
My Git history would be clean.
But my thoughts would be gone.
- I lose context when I come back later
- I lose the trace of why decisions were made
- I lose part of my cognitive process
For me, that wasn't acceptable.
So I built a workaround
At first, it was just a few scripts inside my project.
A way to:
- keep my comments
- generate a clean version before committing
But very quickly, I realized something bigger: this is not just a workaround. It's a pattern.
I wasn't just solving a personal problem.
I was formalizing something deeper:
Code for thinking ≠ code for collaboration
These are two different activities.
They have different needs:
- thinking needs freedom, messiness, exploration
- collaboration needs clarity, structure, readability
Trying to force both into the same branch creates friction — not just in the codebase, but between the people who work on it.
Introducing the Shadow Branch Pattern
We’ve optimized code for readability.
But we’ve never optimized it for thinking.
Maybe that’s the real problem.
The idea is simple:
- a shadow branch for thinking (
feature/x@local) - a public branch for collaboration (
feature/x)
You work freely in the shadow branch:
- your comments
- your experiments
- your unfinished ideas
- your own scripts
- your own workarounds
- your own notes / documents
And when you're ready, you publish a clean version to the public branch.
git-shadow
To make this usable in real life, I built a CLI:
It helps you:
- work on a local "thinking branch"
- keep your comments and reasoning
- publish clean commits to your public branch
A quick example
Start a feature:
git shadow feature start my-feature
Work freely in your @local branch:
/// Get user from database
const user = await prisma.user.findUnique({ where: { email } })
if (!user) throw new Error('Invalid credentials')
/// Verify user password
const isPasswordValid = await bcrypt.compare(password, user.passwordHash)
if (!isPasswordValid) throw new Error('Invalid credentials')
/// Build session for user
const session = await prisma.session.create({
data: { userId: user.id, token: crypto.randomUUID(), createdAt: new Date() },
})
Publish clean code:
git shadow feature publish
Your public branch receives this:
const user = await prisma.user.findUnique({ where: { email } })
if (!user) throw new Error('Invalid credentials')
const isPasswordValid = await bcrypt.compare(password, user.passwordHash)
if (!isPasswordValid) throw new Error('Invalid credentials')
const session = await prisma.session.create({
data: { userId: user.id, token: crypto.randomUUID(), createdAt: new Date() },
})
Your thinking is preserved locally. The /// comments are kept in a separate commit on your shadow branch only.
You can also commit entire notes, scripts, or local environment tweaks using commits prefixed with [MEMORY] — these are never cherry-picked to the public branch. Useful for local dev shortcuts, AI memory files, or anything that belongs only to your context.
Why this matters
This is not about comments.
It's about cognition — and how we actually work.
Coming back to a feature three months later, I don't want to reconstruct the context from scratch. The /// comments are the trace of my reasoning: why did I split things this way? what edge case was I thinking about? Without them, the code is there but the thinking behind it is gone.
There's also a dimension I didn't anticipate when I started: this pattern works remarkably well with AI coding assistants. The shadow branch can hold architecture notes, domain context, and AI memory files — all things that help an AI tool understand your codebase better, without polluting the shared repository.
Code for thinking. Code for collaboration. They're not the same thing, and maybe we shouldn't force them into the same place.
Closing thought
When I was confronted with this team decision, I thought I just had a "weird way of working".
Now I think the tools are missing something.
Maybe we've been forcing ourselves to hide the way we actually think for too long?
If this resonates with you, I'd love your feedback.
git-shadow is available cross-platform and version 1.0.x is ready to use.
Top comments (14)
Tell your co-workers to f' off. Why is their opinion the right way over yours? If you can maintain the code better with those comments, why the f' should they care if the comments are there -- over aesthetics?! "Oh, it hurts my eyes to see so many comments!"
Also, how much of your article was written by AI? I'm not an AI-hater, but halfway through it was just screaming AI. Could be that we see so much AI-written stuff that now we're copying it?
Your reaction was totally mine at first when my co-workers tell me than they cannot toletare my comments inside the repository. But after listenning to their arguments : they will not read them and will not maintains them along the product evolve, I change my mind. Despite the fact I'm really surprise than they not read comments and not modify them, If it's really the case, keeping my comments will add noise to the product and they will be un-sync with theirs related code other times which can be considerate as technical debt.
Now with git shadow, I can keep my comments without the associate technical debt for the team.
About the article, I written it with my own hands and my own thought BUT I ask Claude Code to review it and tell me how to improve it. I follow some of these suggestions which must be teh reason why you feel when you say "but halfway through it was just screaming AI". I must also admit than I'm french native and my english is far from perfect so Claude Code help me to fix this (which is not the case of this comments, which must probably full of english mistakes 🤣). Anyway, thanx a lot for your feedback !
"Tell your co-workers to f' off" - I kind of agree, but I'm afraid it doesn't work like that if you want to remain employed and productive in an organization ... but, I wholly agree that the author's team shouldn't be so incredibly petty/narrow-minded/dogmatic! :D
Hahahaha, love it.
I am not a developer but I ll give my opinion: these people seem to have gotten used to AI code to much. Clean code isn’t good code. The comments are the backbone to understanding someone else’s code, right ?
Deleting your comments is making it harder for anyone but you to understand your code. Heck even for yourself , coming back to something you wrote maybe 5 years ago might be a challenge, especially if there weren’t your own comments for your code.
Wanting to see clean code isn’t one thing , having to sit there and make sense of it is a whole new ball game (at least for me)
Wonderful to see this viewpoint again. It’s been to long. I say advocate for yourself, your views and don’t back down when you can.
These AI Developers don’t know or remember what it was like to code stuff yourself instead of letting AI do the heavy lifting.
Sorry for the rant. Have a great day
Hey Ali-Funk, thanks for the kind words ! And no need to apologize for the rant, it's a real debate ;)
I hear you on the comments as backbone for understanding. That resonates with me too.
But I want to nuance one thing: my co-workers aren't wrong either. There's a real argument for keeping a codebase free of noise, especially in a team context where unmaintained comments can become misleading over time.
The point I was trying to make goes a bit further than "comments or not comments".
It's more about the fact that thinking and collaborating are two different activities and maybe we shouldn't force them into the same place.
git-shadow isn't me fighting for my comments. It's me finding a way to keep my thinking process intact, while still respecting the team's standards.
Have a great day too 🙂
Oh so I misunderstood that. Fair enough! I learned something we today from your response. Thank you so much!
Since I am not a dev myself: isn’t there a way to structure your thoughts and comment in a separate way or make the comments disappear before it goes into prod ?
There are many tools for everything so there must be a way😃, right ?
Yes there is 😀 Usually the team choose to put all the specifications inside a wiki tool, rather directly on GitHub/Gitlab or in Notion-like tools. This choice is motivated by the fact than non-tech team member must also access these informations and we do not want them to be force to download the app source code.
About the inlines comments which are located near theirs associates lines of code (since that's theirs purposes) I think they were no tool before git shadow to make the comments disappear before it goes into prod AND being able to still retrieve them on dev environment after release. Before git shadow, devs must choose between remove theirs comments (if that's the team rules) or keep them inside the prod package (which does not affect the performance of the app in any way). Now they can choose 😁
This resonates with me ... good that you used the experience to build a useful tool, but I think your team should be a bit more open-minded, and less dogmatic - just sayin' ;-)
P.S. looks like a nifty little (?) tool you built there!
In my 12 years as a developer, I’ve worked with over a hundred developers, and this is the first time anyone has commented on my comments. It was also the first time I’ve been asked to delete them.
It seems I’ve stumbled upon the 1% of people who are pretty dogmatic on the subject!
Anyway, let’s look on the bright side: it allowed me to create a really useful tool that goes beyond the initial need to keep my comments 😝
Well I've certainly quite often heard the sentiment "comments don't belong in code", but to me it holds no water without defining what kind of comments we're talking about ...
I absolutely "dig" comments which explain (succinctly, not verbosely) the "bigger picture" which makes the code make sense - context which cannot directly be derived from the code itself ...
Let me just say this - I've worked with some very good developers, and guess what - they added comments to their code!
Great presentation of how you think and like to work and a clever hack to enable you to continue without conflict with your team. Thanks for sharing!
Is this the consensus of your work group? This actually sounds like something that happens with weak management. Code reviewers are free to enforce their own fringe ideas.
Never drank the "clean" code kool-aid personally. When you look at someone's code and think WTF, there are two possibilities. One is that it's bad code. The other is that you've got an opportunity to learn something new.
So when you need to look at a current piece of code, how do you meld all those comments back in?