Hacker News Reader

Comment by Retric | Hacker News Reader

I personally spend significantly more time writing git commit messages than reading them. Spending lots of time looking at old commits is IMO a sign of poor code quality. Similarly, summarizing each change deserves some real thought so when you are reading these messages their actually helpful.

View on HN

Ever spend significant time spelunking in the Linux kernel commit history [0]? They have a guide [1] on submitting good patches, and lots of care is taken to commit message quality.

The commits are quite helpful, not just for diagnosing errors but explaining philosophy and reasoning behind code changes [2]. I'm tremendously thankful for the amount of effort those developers put into this, because it helps newcomers come up to speed and follow development. In that kind of codebase, it would be virtually unapproachable otherwise.

[0]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/lin...

[1]: https://www.kernel.org/doc/html/v4.10/process/submitting-pat...

[2]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/lin...

When your codebase is 5+ years old and was written by 10+ engineers, 2/3 of those are not working here anymore, all you have is commit history linked to task tracking database. So it is naturally the first step of working on a new feature: get to know the subdomain, find corresponding sub-namespaces, look into commit history of those and find related task and specs.

Or you may just punch in a lot of code in hope it will find somehow it's place in codebase and be consistent with other code and readable by your successors and won't break some edge cases not covered by autotests.

Interesting, I favor reading the entire codebase when possible assuming I am going to be working with it for a few months. I only start really looking at old commits only when I need to edit code that’s particularly brittle or incomprehensible.

Let's take exactly 10 engineers and let them work on the project for exactly 5 years. That would be roughly 2500 mythical man-months. Let's say 2000 due to vacations, holidays, non-coding tasks, other tasks and Googlesque 20% pet project time.

Let's say every engineer produces 100 lines of code including blanks and comments per day and deletes another 50. This is anecdotal, you may check your own numbers. This is +250 LOC per week and for our team it means that entire codebase will be 0.5m LOC in 5 years.

I saw a codebase this size once. In 2 years I've read about 1/10 of it.

I’ve read codebases that size, ~0.5m LOC is still generally a reasonable thing to read. With that kind of team and progress the majority of code is likely boilerplate. For example you can skim through most UI, ORM, and glue code only really looking for any abnormal parts of it.

The goal isn’t to understand every line, the goal is to have a basic map of what’s involved. Even a superficial read likely shows you what parts to emulate when you need some of that same boilerplate.

Time wise it’s a good substitute for reading HN etc whisk getting up to speed. Personally, I find it vaguely relaxing so it fills a similar role when you just can’t concentrate on the difficult side of things.

Reading hundreds of thousands LOC does not make any sense for me. When I finish reading I will completely forget what was in the beginning. Heck, I tend to forget my own code in just a couple of months.

It’s not about the low level details it’s what you discover durning the process and building a mental model of the project and the style the code was written in.

Also, memory isn’t just about unprompted recall. If in 8 months you’re looking for how the project generates PDF’s or whatever your not starting from scratch. Sure a full text search will probably bring up a bunch of files but skimming them a second time should look familiar. You may even remember that different sections of code are using two different 3rd party tools because that’s the kind of thing you notice an a first read but might otherwise cause all kinds of shenanigans.

Of course reading takes time, but it’s kind of like negative technical debt. Your prepping so anything else you want to do becomes faster. Asking coworkers about code before they jump ship can clarify stuff in minutes that might take days once they left. Even better you often learn something generally useful on other projects.

If I ever have to fix bugs I'll go and look at the commit history to see where it likely started. Especially if it was code that belonged to me but someone inadvertently commited something that broke it, that's why I like a nice commit history.

> a sign of poor code quality

Or really complex software. Those of us who work in B2B SaaS products know what it's like to understand what a block of code does, but not comprehend why it was written.

However, I don't disagree with this sentiment. I think what most devs fail to understand about git-history is that it's just another place for sparely populated documentation. Your commit history might be AMAZING, but chances are that nobody knows to look for it. There's just too many places where one has to reiterate intent and purpose (doc-string, inline comments, project specs). It's a lot to keep up with - especially for non-technical folk.

Solutions:

What worked best for my team to was a simple git precommit-hook shell script that just auto-tags the ticket number onto the start of every commit message. So `git blame` just points back to JIRA/Asana/Trello/Whatever you're using to document intent. That way, there's a single source of truth for developer documentation that is accessible by everyone.

At Google if there's something that needs explaining you'll see a tiny-url-link that just points to the Google Doc as an in-line comment (i.e: go/my-project-specification-doc). Commit messages do the same. This saves on copy-pasting multiple lines of purpose on every file and line of code.

Reply on news.ycombinator.com