Private comments in git

Question

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?

Answer 1

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...

Answer 2

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.

Answer 3

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.

Answer 4

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.