Hacker News Reader

Comment by a1studmuffin | Hacker News Reader

Hell yes, I use it daily. I'm in AAA gamedev and the codebase I deal with goes back 20+ years. The last 10 years are readily accessible in Perforce and the rest can be found in another version control system. I am forever grateful to past engineers for outlining WHY they made their changes, and not WHAT the changes were per se. With thousands of engineers that have come and gone, this is incredibly useful information in addition to the code itself.

IMHO revision history is just as valuable to a company as the code itself.

View on HN

> I am forever grateful to past engineers for outlining WHY they made their changes, and not WHAT the changes were per se.

So true, we have this one senior developer who gets mad if someone's algorithm isn't as efficient as it could be (fair enough I suppose). But we can't get him to use commit messages that are more than 1-3 words and simply mention a word or three about the area of code that was changed. Years later, he also can't remember WHY he made those changes, so I'd much rather work with someone who writes inefficient algorithms that are easily improved at any time than commit comments that are forever useless.

What was changed is easily seen in the commit itself, why needs to be in the commit message.

"What was changed is easily seen in the commit itself, why needs to be in the commit message."

Commit message is like subject of an email. Is n't it faster to look at commit message, and get an idea about change rather than go through commit and understand it?

Yes, fair enough... having both in the commit message is ideal. I just mean that the absolute minimum is the why because at least the what can be deconstructed from the commit.

The first line of the commit message should be the "subject line". The rest of the commit message should contain a summary of the high-level stuff such as the "why".

I wonder why is it so hard for people to right good commit messages. At my company I've actually tried trying talking in-person to people, even write a doc explaining the benefits and how to do it, pointing people to good resources like this one: https://chris.beams.io/posts/git-commit/

And still, I can't get people to do it. I find it so valuable to look at commit messages that are written, that explains the why behind the changes in the commit but can't get people to see the same value as I do. Any tips on that? Would be really appreciated. :)

> I am forever grateful to past engineers for outlining WHY they made their changes, and not WHAT the changes were per se.

Oh, so much this! The same applies to in-code comments. If your revision notes (or your code comments) are only telling me what I can plainly read in the code, then they're utterly pointless. Tell me what I can't read in the code: the "why"s, as well as potential consequences and "gotchas" the changes may present.

> I'm in AAA gamedev and the codebase I deal with goes back 20+ years.

I'm curious what parts you work on (engine/tooling?). I've always had the impression that games usually have more throwaway code than other types of applications.

Well, the Unreal Engine is 22 years old. I doubt the current incarnation is free of legacy code.

The current version was developed from scratch.

Until the OP mentioned Perforce, I was 100% sure they were a co-worker of mine. I also work on a 20+ year old project, mainly on the core graphics/game engine. It’s mainly used to power a single game franchise, although I’d say that any commits from more than 2 major versions ago aren’t all that useful anymore. Too many things keep changing especially around the area that I work on.

Could easily be a sports game. That was my guess, then I remembered that the quake engine powered Half Life 1 forever. Could possibly also be working with the iD engine?

How's the AAA industry nowadays? I got out awhile ago (though HoN never really counted as AAA) but it was a fun ride at the time.

Is work life balance a bit better now, or does everyone still push themselves pretty hard?

It's both better and worse than its ever been.

There's an awareness and discussion about "sustainable" development practices, but a large portion of our workforce had to leave for stress reasons last year, on a project that is saying "sustainable development" the loudest.. so while it feels like lip service, at least there's an awareness at some level.

(also, gamers are more entitled than ever, so we're always running; which causes our games to be buggy as hell which slows us down later.. horrible and completely unsustainable)

I’m making a game of my own right now and am curious about the larger industry

- is it common for AAA companies to claim ownership over all ip you create, even outside work? (My last job did this)

- How would one find part time or short term contract work in the games industry?

> - is it common for AAA companies to claim ownership over all ip you create, even outside work?

Yes. This is super common. Depending on the company you can make some kind of agreement. Most agreements are based on income (so if you make a lot of income you need to renegotiate, something 10% your yearly salary or something).

> - How would one find part time or short term contract work in the games industry?

If you’re an artist, I guess this is easier because those are contracted out positions. But for others it’s unlikely the company will hire you for part time work. They seem to want everyone giving 111%, a part timer might be useful but could cause blocking issues.

But that sounds like you value documentation, not necessarily the code history

Code history is documentation. There are lots of different kinds of documentation: code API level, module level, system level, tutorials, even books in some cases. Revision history is just another one of those levels, and I believe it is the best at capturing the "why"s of systems rather than just the "what"s.

I agree code history can be used as a form of documentation, but in cases like this looking through years of code to find the decisions/reasons leading to a particular design seems like inefficient communication. It seems like "real" documentation with a few sentences explaining directly would be more suitable.

I disagree. In some cases, code history can be much more efficient. You really need a mix of both.

There will be things that are much better captured as part of a revision/commit, especially if your commits are well-designed, grouped into logical chunks, and include messages themselves (and maybe are linked to a project management tool).

You will need information like "this code was added as by X as part of work they were doing on Y, and they also made changes in other parts of the code as part of that". That context is really valuable.

You can think of it like event sourcing, which captures a lot more information than traditional mutation of data, and as a pattern, is a lot more rock solid... except event sourcing for your data is (usually) much more difficult to implement in practice, and code revisions are already an almost completely solved problem.

Capturing most of your data in your commits/revisions seems to suffer from a lot of the unsolved event sourcing issues:

- How do I quickly find the info that I want? How do I "query" the commit log? Often times, we want a "view" of the history which tells us specific info. If I need to scan through half of the commits just to get a good understanding of the architecture of the code, then that's more wasteful than just having a design doc. If I'm troubleshooting a production bug, then the granularity the commit log offers becomes important enough to offset its slow "query" speed, so I'd want enough "why" commits in the commit log and outside of people's heads.

- People write to the commit log without a well-defined "schema". If you use something like tags, how do you handle changes to the tags ("schema evolution")

This is my train of thought for why I lean towards "why" comments near the code or in a design doc over commit messages, which I allow to be a more sloppy.

A higher-level thought: The attractiveness of the event sourcing analogy often comes from assuming that the commit log should be a strongly consistent source of truth. However, it's good to remember that a huge amount of info about the code is stored in the team members' heads. In particular, the code writer knows a huge amount that can't be easily documented. So an alternative analogy would be to think of each member as a VM attached to block storage. If a VM fails (the person gets sick) or leaves the cluster (they leave the job), then you lose all of the data in block storage. So, the team wants to facilitate just enough overhead/admin work to transfer important data from individual team members to shared but slower storage (like the commit log, design doc, comments, etc.)

I recommend checking out Peter Naur's essay "Programming as Theory Building"[0] as it touches on the subject of a program being more than the code + documentation, it lives on its designers' and developers' heads, their intents, visions, etc.

[0] http://pages.cs.wisc.edu/~remzi/Naur.pdf

You might find some weird hack in codebase that isn't obvious what it does at the first glance. This isn't something that people document in official documentation but even finding a JIRA ticket that is linked with that specific commit can help tremendously.

I personally think of version control history as like a sedimentation layering of documentation that "updates" itself in the process of doing the work -- like the desk that looks messy, but by picking up and using papers, the most important stuff is on top. "Real" documentation can be clearer, but it must be maintained manually, and cleared out regularly. VCS kinda handles this with less process weight.

The right tactic is def a mix of both though, so I think I'm in agreement with you :)

It's because "your commit needs to link to something in the bug tracker" is pretty easy for code review to enforce, but I have never seen an org manage to indefinitely keep an accurate as-built design doc beyond the code itself. You can convince people to write new aspirational design docs for intended major changes, but after approval those never get updated to reflect what really got built, and lots of small bugfixes don't get one at all.

This is a great comment, except for the last line, which is extreme hyperbole.

Parent clearly stated it as opinion.

Isn't it a tautology? Revision history includes the code itself.

Reply on news.ycombinator.com