Hacker News Reader

Comment by VBprogrammer | Hacker News Reader

As an example of what I'd like to read:

  #2313 Change expected value to a float field.

  django-haystack stores decimal fields as strings internally.
  This means that when we order by expected value small
  values (e.g '9e-08') are sorted before larger values.

View on HN

I prefer to keep such comments in the code, not in the commit message. It is highly unlikely that anyone coming to do some changes to that part of the code would go and read a year-old commit message that he isn't even aware exists.

Try using git blame. It tells you what change caused a line to happen. I often use it to find out exactly what issue caused a seemingly crazy bit of code to happen. As the code goes away, so does the commit message - not necessarily so with a comment.

While that's true; `git pickaxe` will also do what you describe. The added bonus is that one could use pickaxe to follow a specific line's changes way farther back than a normal comment.

http://jfire.io/blog/2012/03/07/code-archaeology-with-git/

There is a difference tough, a very subtle one. A commit body should describe the rationale of the change, i.e. any decisions that had to be made or trade-offs in light of developer discussions and so on. Basically a description of the issue being solved. These things are rarely needed in the code itself, as the code will most likely feature new things and the old things are history.

Some commits even feature implementation details, and those I agree with you sometimes it makes sense to include them in the code. However most implementation details replace old ones, and this is transition should be explained in a commit since this is the perfect place for it.

Here is an random example from the linux kernel, which is guaranteed to do what I described: http://goo.gl/QdKNnJ

The example I gave (happened to be what I was working on) would be quite pointless as a comment. Since the code could easily have been written using the float datatype.

You can run git blame to get the information pertaining to that particular line of code. That's a really good way to document what a particular piece of code is doing and why at the time it was written.

This is a great example - it's details, explains the issue and also has the bug id (presumably) in it.

Reply on news.ycombinator.com