I need to add a feature to some code in a big project and due to the complexity I find it very helpful to add detailed comments to many lines to keep track of what's happening. This is only for my own understanding however and I will delete the comments before pushing the code.

The problem however is that if I do private commits during my development, when I push to the main server, I guess git will show the lines that I commented and then uncommented (but didn't otherwise modify) as being modified by me, making "blame" more opaque.

I suppose the only way to do this cleanly is to have 2 private branches, one for development and one for commenting, or can anyone recommend a better way?

  • 3
    What about using git rebase for squashing commits before pushing? Jan 6, 2014 at 6:54

4 Answers 4


To directly answer your question:

If you take care to always use separate commits for adding comments, you can later remove these commits (using git rebase -i). As long as the comments and the other code changes do not touch the same lines (or lines very close to each other), the rebase should not produce any conflicts.

However, I agree with Doc Brown that you should try to write comments that can stay and help others. Of course, doing a final pass with rebase is probably still a good idea, to improve/fix comments (as your early comments might have been incorrect).

Also, instead of using comments, you might want to change variable and function names - that is often a better way to improve readability. But that's another question...

  • Thank you. I didn't realise this was possible with rebase. Ideally I would like to push the comments-cleaned version to the server whilst retaining a comments-not-cleaned local reference. I suppose this would require separate branches, unless you could suggest a solution in combination with your rebase method?
    – Gerhard
    Jan 9, 2014 at 4:32
  • @James: Yes, one option would be to keep your private comments on a private branch. Then you can transfer (using merge, or cherry-pick, or copy branch+rebase -i) only the changes you want to publish to another branch which you push. However, keeping this "private" branch up-to-date can become tedious (and you must constantly be careful not to push it accidentally), so I'd probably rather not do that. Rather, find a way to put your private changes into a form that can be pushed.
    – sleske
    Jan 9, 2014 at 8:29

So you need to add lots of comments to make the code readable and understandable - which is often a sign of, lets say, mediocre code quality. What makes you believe other team members would not benefit from those comments as well? Or that you won't need them again later, when you have to look at the same code again? Learn to write those comments in a way you don't have to remove them afterwards.

Or even better, instead of writing many comments, learn to refactor the code in a way it becomes more self-documenting, so lots of comments can be omitted.

If you really think you cannot change your habit of working that way, I suggest you leave your comments adding-and-deleting in the history. In a good team, there should be no reason to hide the way you work from the rest of the team.

  • 2
    +1 to not removing the comments if they are necessary to understanding the code. Jan 6, 2014 at 8:10
  • Thank you for your answer. I can see merits to this approach in certain situations too. As I followed-up to sleske's answer, I suppose there's no way to retain private comments without creating a new branch if I use the rebase -i method?
    – Gerhard
    Jan 9, 2014 at 4:48
  • 4
    If you need comments to write the code, then clearly I need the comments to be able to maintain the code.
    – gnasher729
    Jul 11, 2017 at 8:52

I agree that git rebase -i is correct way to remove local changes before pushing.

I also agree that if you feel the need to add comments to make the code understandable, they are likely to help your colleagues as well and therefore you should push them.

In either case the comments should be added in separate commit where you don't change anything else then comments. If you add the comments a bit at a time, you may consider combining the commenting commits using fixup command in git rebase -i to push in fewer pieces.

If you put the comments on separate lines, blame will only attribute the comment lines to you but not the code lines as they didn't change. Generally the code should not be too wide so it fits on the screen with IDE toolboxes on both sides, so there is rarely enough space at the end of line to do much explaining anyway.

Even if you do touch the lines and the blame will start attributing them to you, there is usually many changes to a line and when looking at a blame annotation, it's rare to be looking for the last change. There is no excuse for not looking at what the last change to the line was and not redoing the blame from the previous revision.

This is one of the reason why preferred option to be used when looking for some code is the "pickaxe", git log -Stext (and git log -Gpattern). If you give those only the code on the line, they won't find the commit that added a comment, only the commit that actually introduced the code.

And remember, making the code easier to understand, at least by renaming things to be more descriptive, is better then comments, because comments may become stale as the code is refactored, but the code itself can't.


I have one more recommendation, though it's only partially relevant.

Put explanation of the code in the commit log!

When you do a change, especially to a code you don't understand very well or code that is non-trivial or non-obvious, it is useful to dump all your thoughts you had when making the change in the commit message.

Include what you found about how the code worked, detailed analysis of why it was wrong and explanation of how the change is supposed to fix it.

Unlike comments in the code that often get stale, comments in the commit log are attached to particular state of the code and can be selectively brought up by blame or "pickaxe" (log -S/log -G).

So next time you need to change some code, you'll run blame and log on it and read the comments and you should find all the explanations of how the code evolved with clear indication of which obsoletes which. And all that without cluttering the code.

Of course the comments should still stick to mainly explaining why and what in high level terms, while the low level terms of what and the how should be obvious from the code and if it's not, cleaning up the code is much better then commenting it.

  • 4
    I don't think it is good solution to put comments which belong to specific lines in the code into the commit log instead of directly in the code. A commit log should only contain information about what you have changed. A comment about a part of code which is hard to understand should stay as near to the code as possible, and it should stay there as long as the code is not refactored, which may be for several revisions.
    – Doc Brown
    Jan 6, 2014 at 8:49
  • @DocBrown: Yes. But the problem with comments in code is that they invariably remain there even when the code is refactored. And such comment is actually worse than no comment, because it becomes actively misleading.
    – Jan Hudec
    Jan 6, 2014 at 9:15
  • that can be indeed problem, but I don't consider you idea as a good solution for this. The only real solution is IMHO the things you mention in your last paragraph. P.S. I did not downvote your answer and don't think it don't deserves such treatment, I like to hear other opinions about such a topic, even when I don't fully agree to them.
    – Doc Brown
    Jan 6, 2014 at 9:27
  • considering the extra operations to access the information vs the "in your face" comments will be in the code. I personally would not think of looking in the commit logs, least not until I've exhausted other resources found in the code itself to answer whatever questions I might have. I'd say in this mode the efficiency at which one understands the code would be marginally be better as when there were no comments in it. By efficiency here I combine accuracy and speed.
    – Newtopian
    Jul 11, 2017 at 14:02

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.