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.
Recent...
For further actions, you may consider blocking this person and/or reporting abuse
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?
"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
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 !
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!
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.
At first, it was my technical manager’s decision.
Then, seeing that it was impossible to have a constructive conversation with him on this topic, I wanted to revisit the decision with the entire team. A roundtable discussion quickly made it clear to me that I wouldn’t be able to convince them easily. Since I’d only been with the company for a month, I decided not to push the issue too hard.
And anyway, I now had my Plan B: git shadow
Sounds like a partial implementation of literate programming
I wasn't aware of this concept, thanx a lot for sharing !
Here's the wikipedia page for those which want more informations about literate programming : en.wikipedia.org/wiki/Literate_pro...
I see the parallel you're drawing, but at the same time, it's clear to me that this isn't at all about achieving what's done in literate programming.
You mean like interleaving explanatory, prose-oriented meta-information with code, while allowing a code-only view? If you say so 👍🏻
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!
La verdad es que tus compañeros son unos pendejazos. Busca compañeros que si usen comentarios, son valiosos. Hacen el código más legible. Y revelan el principio generador del código, no cabe duda que en todos lados hay imbeciles.
😂🙏
So when you need to look at a current piece of code, how do you meld all those comments back in?
All local commits are stored in the main shadow branch (e.g., main@local), so I just need to switch to that Git branch.
A sync from main to main@local is required to work on the latest version of the code. That’s why Git Shadow provides a “git shadow sync” command, which handles any conflicts using a Git rebase that runs in the background!
Yikes. It is a shame your group is that strict about comments. That is so counterproductive.