Hacker News Reader

Comment by nickbauman | Hacker News Reader

Generally, time spent twiddling with the repo is time not spent delivering code. It's a distraction. Yes git has all these features that lets you do that and those feature matter when you're committing to the Linux repo which has thousands of eyes and your commit history has to help you communicate to a very wide audience. But the vast majority of us are not using git like this. I've used git bisect so rarely all this is overkill.

View on HN

- Generally time spent writing documentation is time not spent delivering code.

- Generally time spent commenting code is time not spent delivering code.

- Generally time spent diagramming on a white board is time not spent delivering code.

- Generally time spent writing specs is time not spent delivering code.

Yet, doing all of these are actually extremely important. How much importance you give each one of them is up to you that's for sure.

So, "Generally, time spent twiddling with the repo is time not spent delivering code", is true, it's nonetheless important, and, this statement disregards the fact that "twiddling" usually only takes a few minutes.

I've never seen documentation efforts pay off in organizations that do not have documentation as a deliverable artifact to outside stakeholders.

I've never used commit comments to store important information about the systems I'm working on. OTOH I can see people working on Linux needing that a lot more than I do.

Feel free to twiddle if that floats your boat though. I will refrain from twiddling, thank you.

Time spent twiddling with the repo is time saved in the future debugging or writing documentation.

You can have large refactoring PRs for which splitting them further really makes little sense(*), but that have a huge risk of introducing regressions. Being able to bisect them is much easier with a properly maintained repository.

(*) And then you spend time twiddling with GitHub, which is the same as twiddling with the repo except with worse tools.

Time spent "twiddling" with the repo is time spent documenting the business reasons for code changes. Depending on what type of code you're writing, this might be not-so-important or massively important for future understandability.

Business reasons for code changes are kept in JIRA tickets and in merge requests. Comments might also explain business or technical reasons for certain chunks of code.

Commits are just logs of the units of work done to support completing those tasks. They often don't have any real logic for where they're broken up except that it happens to compile or that I want a checkpoint that can be stored remotely for safety.

> Business reasons for code changes are kept in JIRA tickets and in merge requests.

It's fine for JIRA tickets or merge requests to have the meat of the details. So this commit message:

  PROJ-431: split function

is much better than just:

  split function

because although git blame does not give me the reasoning directly, at least I can read the ticket and hopefully understand it in minutes. In the latter case, there might be some later commit within the merge request that does refer to the ticket number, but Git does not have a quick way of finding later commits, so you might have to muck around with the log for some time to find the actual ticket reference.

But with a commit message like:

  PROJ-431: Separate base lookup and filtering
  
  For the Foobar customer, this data needs some special aggregation
  after lookup but before sending it to the main filtering function.

, it takes literally seconds between seeing a curious line of code and understanding why it was put there. Depending on how often a reader of the code has to do this, it may or may not be worth the effort. But in my experience working on decades-old projects with thousands or tens of thousands of commits, it makes a significant difference to productivity and the rate at which a new developer understands the code.

Reply on news.ycombinator.com