Hacker News Reader

Comment by db48x | Hacker News Reader

In theory yes, but in practice I've rarely been satisfied with the 'why' of a change unless I was able to talk to the author about it. Everyone seems to leave these things out of commit messages, because they seem so obvious at the time. Bug trackers are often better for this than version control.

View on HN

This is something that I hammer into newer members of my team (mostly about code comments rather than commit messages):

The comment that tells you what happened is merely saving you some time parsing the code. The comment telling you why it's done like that is completely irreplaceable.

It has earned me the Stickler moniker, and I'm absolutely alright with this. They've never had the displeasure of refactoring code from 3 years prior where the function's name is getIpAddress(), but it does 6 additional things within the method. The docs says, "Gets the IP address". The commit message says, "gets user's IP address". The function really gets the IP address, does some weird encoding (of which I'm still not sure why), does some other stuff with the request headers, then returns the IP.

Documentation saves lives, people.

"Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live"

You may want to also consider refactoring this code. A function should do what it says, not have unexpected side effects.

Not only can this be surprising to a client, but it also makes it difficult to leverage the code for reuse elsewhere ("I only wanted the IP address, not the rest, guess I'll write one called getIpAddressOnly", etc).

Functions like this also tend to become muddled and difficult to maintain because as time marches forward, functionality may need to be added between these side effects, and again, unless it is refactored, it has to end up within the same function, making the whole problem even worse.

the best thing in life (almost better than hearing the lamentation of their women) is when there's a good explanation WHY it's done like that and later someone changes the code while not updating the WHY (writing documentation is for people who don't get things done).

Agreed. I guess that he is not practicing basic software engineering. Developing code is not just updating code and then check it into version control with a helpful comment. They should be some documentation for the "what, how, who, why" answers.

I sympathise with this point of view, but I think it misunderstands what Tarn is doing. DF is a weird (also fun and deeply rewarding) piece of outsider art. Source code is his medium, but expecting him to apply professional software engineering practices is like expecting Andy Warhol to use the same process as Campbell's when making the label for a soup can.

That's a really great way to look at it, thank you :)

Commit messages with a link to the bug tracker and some short description are the best IMHO.

Reply on news.ycombinator.com