[avar]

One thing I've changed about my style in the last few years is to almost never comment my code, but to instead write long and detailed Git commit messages explaining the how's and why of that code at the time that I write it.

That means that over time I effectively have comments for every line of code in the program, but it's associated metadata instead of being embedded inline, which means that the comments never go out of date, and their history is accurately tracked in version control.

[bcl]

The problem with doing it that way is that someone who comes across a checkout of your code will have no documentation. Think about the case of a distributed tar.bz2 or having a python application installed on your system.

I prefer to have the comments in the code, in a form that can be used to generate documentation on the side (eg. doxygen, epydoc, etc.) so that they can't get lost, and so that you can read them as you read the code. It is difficult to re-combine the git commit messages with the code, but not hard to extract the comments from the code to create documentation.

[MatthewPhillips]

So anyone looking at your code and doesn't understand why you implemented Foo the way you did has to dig through 500 commit messages to find when it was added. Or worse, you are working with 2 dozen other programmers, all working under their own forks, and they have to look through all of that since they don't know who was responsible for adding the code. Thanks.

[MatthewPhillips]

Expected response: git log | grep Foo

[nitrogen]

Or "git blame filename.py" followed by "git show SHA1".

[hndl]

You're likely to cause a lot of trouble for other (possibly new) engineers going through your code. It seems cumbersome to look up metadata side-by-side while going through code.

I, personally, always reread my code in the form of sentences. Something along the lines of: "okay, first I create a x. Then I pass y to it. I then set this flag..."

If at any point I hesitate or have trouble stating what a line of code does, I add these sentences as comments so someone else can understand easily/quickly (if I can't alter the code for some reason, that is).

[jevinskie]

Inline comments are accurately tracked in version control. I don't see how updating comments when you update the code is any different except for the obvious advantage of seeing the comments right next to the relevant code.

[chc]

It's really easy to miss updating a comment somewhere. I mean, people introduce bugs into programs even with extensive automated tests. Rendering a comment obsolete is something your tests will never catch, so it's easy to miss the fact that you've broken something until you actually need the comment.

By contrast, it's nigh impossible to forget to include a commit message, since failure to do so will cancel your commit.

[TheCapn]

I'm on your side. If dates are an issue then have a change-log noted in the source code file where you create a tag (such as initials+date) and insert that above large code changes so you can see code commit changes based on date within code as well.

Comments don't take up much space (reading or on disk) so don't think its bad to be verbose.

[1337p337]

You don't actually lose the metadata by commenting the code, thanks to git/svn/hg's blame feature, named identically in each. (I've not used darcs in a very long time, but it had something similar called "annotate".) If the code doesn't look like the comments say it is, you can check the timestamps and if that doesn't help, then you can crawl through old commits to see what's going on. It's useful enough that I've bound a key in my editor to display the blame'd code.

[jberryman]

That's sounds interesting. I'm a bit of a git newb; what git commands or tools do you use to make this convenient?

[electrum]

IntelliJ IDEA or any of the JetBrains IDEs based on that platform (RubyMine, WebStorm, etc.) have this built-in: right click in the gutter and choose Annotate. Mouse over a line to see the commit message for the most recent change to that line. http://www.jetbrains.com/mps/whatsnew/screenshots/20/annotat...

[angelbob]

"git blame" helps too - yes, you know it was you, but that tells you what commit added that line. Now do "git log -p 31dc4a" (or whatever) to see the commit's comments.

[MatthewPhillips]

git commit :) Which is required before pushing any code.