Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
3  
What about using git rebase for squashing commits before pushing? –  MarcDefiant Jan 6 at 6:54
add comment

4 Answers

up vote 5 down vote accepted

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

share|improve this answer
    
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? –  James Jan 9 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 at 8:29
add comment

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 that you don't have to remove them afterwards.

Or even better, instead of writing so many comment, learn to refactor the code in a way it becomes more self-documenting, so you won't need so much comments in the future any more.

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.

share|improve this answer
1  
+1 to not removing the comments if they are necessary to understanding the code. –  sevenseacat Jan 6 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? –  James Jan 9 at 4:48
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
3  
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 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 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 at 9:27
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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