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 (0)