Hacker News Reader

Comment by ep103 | Hacker News Reader

I know the OP didn't mean it this way, but after reading HackerNews for the last decade or whatnot, it never ceases to surprise me how often developer complaints stem from developers just not doing their damn job.

"Almost nobody ever sees it.... nobody reads anything other than the first 50 chars of the headline."

On the one hand, I get it. If a tool makes something difficult, people are less likely to do it, and as engineers we want to make tools to cause people to fall into the pit of success. So, improving this part of git makes sense.

On the other hand, just do your damn job. If a coworker doesn't understand a code change, because they didn't bother to read the commit message, they're a bad developer. If they didn't write a git commit message because "no one is going to read it anyway", they're a lazy engineer. These things aren't excuses, they're incompetence, and not everything needs to cater to the least competent people in our profession.

View on HN

When I document, or write commit messages, I don't really _care_ if other folks will ever look at them. Documentation is a gift for future me. If something wasn't obvious to figure out, or a potential source of future problems, I want it written down, so if _I_ go looking for info, it's there.

The fact that things are now documented for other folks is just a side benefit.

This.

I write documentation for me.

Very few folks ever use my published code, which is fine by me. I publish it, because treating my packages as atomic, ship-ready, high-Quality products, forces me to take great care, in each and every one.

Which means, when I use them in my other work, I don't have to worry about them.

My take on documentation is thus: https://littlegreenviper.com/miscellany/leaving-a-legacy/

Documentation is for everyone. Put it where everyone can read it, not hidden in the most esoteric place possible, via a very unfriendly tool.

I do that often and call it the developer guide. After the user and ops guides.

Not to mention comment and doc strings about why in the current code.

This entire thread is making me feel like I'm taking a crazy pill.

A simple git log is considered "esoteric" these days? No extra command line arguments are required to read the entire commit message. If so software "engineering" is truly a dead discipline. I guess the "move fast and break things" crowd have taken over.

Not sure why you're attacking me. I don't remember saying anything offensive.

Anyway, I've never been a fan of "moving fast and breaking."

Might want to give that blog entry I linked, a read.

Never worked with other people? Git as a thing is off the table.

Which commit? One month ago or three? Pro{gram,ject,duct}M, SME, QA, or user wants to know why? Do they even have a login to the systems they’d need? Is there search so they could find it themselves when you quit?

Or you could send them a link to the docs.

I feel like it's not a question of "doing your damn job". It's a question of what value can you expect to get from a particular investment. If blame is your tool and every line happens to be changed from a different blame invocation (is it "-w", "-w -C", "-C -C -C", etc), how do you learn the story of this block of code best? Maybe you then need to read a story _per line_ of code. But that's not actually worst case. Maybe you need to drill down to the commit _before_ that because the last change isn't semantically important. Maybe the one before that, etc. How many commits that touch those lines significantly do you need to research and read amazingly well written commit messages before you totally understand the context of this particular block of code?

Coding is a really interesting field in how quickly it's developed, and I think there's a lot of people who assume their environment is the only environment and it should be that way for everyone.

Spending time digging through commit messages when tooling and design makes it harder, not easier, is a risky proposition if it turns out it was all fucking useless and you didn't find anything worth reading and are now even farther behind. Either due to the quality of the messages or a lack of your ability on your end to find what you need.

I'd love to work in the sort of environments these people seem to but it's just not been the case. I'm at a smaller company where I get to wear many hats, and coding/development is just one of them, but I know plenty of people at very large companies who also don't really do things like that because "putting in the effort" isn't rewarded as much as whatever arbitrary metric they're graded on.

Git visualization isn’t git’s job, providing primitives like blame for git visualizers is. If you use VSCode with gitlens (pycharm is similar), the exercise you just mentioned is trivial. Focus a line, get the correct blame. Click on that, view the commit history. Click from there, see the diff.

> it never ceases to surprise me how often developer complaints stem from developers just not doing their damn job.

One thing I learned is that any forum that appeals to software engineers will appeal to software engineers of all skill levels, from the guy that did a 6 week coding camp because he heard SWEs make a lot of money but didn't really learn anything but thinks he's an expert now, to geniuses with 10+ years experience.

For every comment from someone who really knows what they're doing, there's one from someone that really doesn't.

Yep. This is one of the big problems with online communities. When someone makes a bold statement, I have no idea if they’re a grizzled engineer with grizzled, hard earned engineering opinions, or some kid fresh out of a coding bootcamp who thinks they’re all that. In person, I’d treat those two people incredibly differently. Online? It’s impossible to spot the difference.

It doesn’t help that we all think of ourselves as programmers, even though people in our industry have a wide range of jobs. Someone working at a feature factory banging out websites and mobile apps has a very different job from someone slowly puzzling out a new cryptography algorithm or debugging a kernel driver. You can tell they’re different jobs because excelling in those roles takes different skills. In the first case, you want to know your domain backwards, have great social skills and work consistently. In the later cases, you need deep CS knowledge, patience and insight. It’s different.

Who is this site for? What does everyone do for your job? It’s all quite unclear.

Once I started interviewing - mind you, interviewing candidates that already got through several filters before getting in front of me - I realized how mediocre the average engineer is. Should it then follow that the average engineering opinion online is mediocre?

pretty much yes, even here you see a lot of overconfidently mediocre takes

It’s important to know how to stick to your course in the face of bad advice.

> Yep. This is one of the big problems with online communities. When someone makes a bold statement, I have no idea if they’re a grizzled engineer with grizzled, hard earned engineering opinions, or some kid fresh out of a coding bootcamp who thinks they’re all that. In person, I’d treat those two people incredibly differently. Online? It’s impossible to spot the difference.

I know there are limits to this, but isn't that a good thing, too? It's all too easy to treat a newbie as if they can't possibly have useful things to offer to the community; being forced to treat all comments equally, without being able to fall back on the crutch of reputation, arguably forces one to read and engage more deeply with the content, and offers the chance to surface the occasional genuinely valuable contribution from a newbie (or, for that matter, to avoid letting someone get away with an ill considered or overbroad statement just because they have such a big reputation that people are too afraid to stand up to them).

True, but occasionally a newbie offers a solution to a problem and rejects the rejection when people try to tell them why their solution won't work.

For example, several years ago here on HN, during a thread about cryptography, someone admitted to not knowing much about cryptography, but offered one-time pads as a solution to the weaknesses of PKI. I tried to tell them that OTP solve a different problem that is unrelated to PKI, but they wanted nothing of it. They claimed that my response was purely emotional and that just because I knew more than them about cryptography doesn't automatically make them wrong. When I tried the Socratic Method to lead them towards an understanding of why they were wrong, they accused me of being condescending and said that I should answer my own questions.

If I see a bold claim that I have a hard time believing, then I'll ask follow-up questions. But when someone makes a bold claim that is just factually incorrect, while admitting they don't know much, and then get upset when someone tells them why it's incorrect, then that's just plain frustrating.

> If I see a bold claim that I have a hard time believing, then I'll ask follow-up questions. But when someone makes a bold claim that is just factually incorrect, while admitting they don't know much, and then get upset when someone tells them why it's incorrect, then that's just plain frustrating.

But that doesn't seem a situation that would have been addressed by fixing the problem that you originally identified:

Here, it sounds like you knew on which side of the divide a person fell. The resulting problem is still a problem, but it's one that also occurs offline!

Any system where the proposed solution is "be better" without an outline of "and here is how" and some method of enforcement is doomed to fail.

Checklists, build checks, linters, tests, SLOs, post incident responses, follow up tickets, etc all serve to unload "be a better software developer" into actual systems and processes that can continuously enable the better behavior.

Simply stating "do a better job" wont work as organizations scale. Related, you can expect what you inspect.

There were two hands in that comment (on the one hand/the other). One hand said that Git and other tools should be better. Only the other hand said to be better.

> If they didn't write a git commit message because "no one is going to read it anyway", they're a lazy engineer.

If an engineer spends an hour writing a commit message that no one reads, that's an unproductive engineer, compared to where they should be.

I have to admit, I am lazy. I don't spread seeds by hand; I use a tractor. I don't swim across the ocean; I use an air plane. Likewise, I don't write documentation in commit messages; I write documentation in PR descriptions, READMEs, and official document sources. You got me, I'm incompetent.

My "job" is to write software, not follow some arbitrary "pure" practices.

> If a coworker doesn't understand a code change, because they didn't bother to read the commit message

And I would argue we shouldn't cater to developers who make documentation difficult to access for everyone else by hiding it where only crappy tools can reach it.

> If an engineer spends an hour writing a commit message that no one reads, that's an unproductive engineer, compared to where they should be.

Okay, maybe don't spend an hour. It would take a special kind of commit to need more than a few minutes writing a decent commit message.

> And I would argue we shouldn't cater to developers who make documentation difficult to access for everyone else by hiding it where only crappy tools can reach it.

Yeah. Like web browsers. And PDF viewers.

The non-caustic point here is that clearly different people have different ideas about what is accessible.

If writing good commit messages isn't specifically defined as part of your job, why would you waste business hours writing commit messages that are beyond what is expected of you and frankly useless since nobody would ever read it anyway?

I'd do it for CYA purposes in case smt goes wrong and my commit is involved.

In my company we norm the titles of MRs, give it a ticket number and squash it all. If you can’t concisely describe what you did you need to split your MR.

Helps with reviewing as well as blaming.

Writing good commit messages is part of your job in the sense that no reviewer should be approving anything without them, knowing that you may or may not be available if it breaks next year at 3 AM.

I put that kind of thing in the pull request, since that's where the review happens. Every commit links back to a pull request, and people actually do refer back to it. Writing good documentation there is part of the job.

No-one's going to ALSO write commit messages that no-one will see.

The git history will last longer than the platform hosting the PR.

Not only is “git log” always up, I can also skim it without opening a hundred browser tabs.

pull requests don't live in the repository (as far as I can tell...) and require you to use whatever online interface creates them.

Not sure whey e.g. Github Pull request merges don't include the entire pull request description in the merge commit message.

In my opinion PR/changeset description is exactly what should be in the commit description. In cases were we had 1 commit per PR (i.e. squashing before merging) just copying the PR description into merge commit worked really well - the goal for a PR description and a commit is essentially the same.

I wish github allowed to make the copying automatic and ensure that it happens (it doesn't, unfortunately).

If someone wants to learn the full history - the remarks during code review, perhaps all the WIP commits - they can read the PR/code review comments. I found it to be very rarely needed.

settings > allow squash merging > default commit message > pull request title and description

Oh, nice, thanks. I haven't been using github recently, it looks like this option was added ~1.5y ago.

This is exactly how Microsoft Azure DevOps works when you enable the squash-on-merge behavior (which is how we used it while working at Microsoft). I thought this was completely logical and I'm surprised that GitHub can't be configured the same way.

All of our commit messages were nice, long and detailed, with a link back to the PR if you really wanted to go back and see the individual commits and/or discussion that occurred on that PR. I think I only looked at individual commits maybe once or twice since they were usually useless in isolation (woops, WIP, fix typo, etc.).

Why would I waste time reading this paragraphs long commit message when I can look at a diff and a 40 character headline and completely understand the issue? You think it's lazy, I think this is wasteful. Personally I don't need an epic story about making a one character change because your editor isn't configured to catch gremlins... it's just not that interesting.

Because you don’t actually understand the subtleties of the side effects of that 40-character change and building intuition about it takes a paragraph.

It’s all fun and games until your codebase is >1,000,000 loc.

This code never worked but made it into production. What I see is a developer hucking garbage over the wall, not testing their own code, passing reviews assuming they exist, and eventually stopping the train in its tracks because they're more concerned with pretty commit messages. I also think this is beyond simple to catch early be it the editor, the pre-commit hook, or any other range of tools that could have and should have prevented this.

I'm not saying a detailed commit message is never warranted, I'm saying this fuck up doesn't warrant a short story let alone a prize for being overly verbose. BTW, I did a loc . on the repo I work in, came back with 7400000 lines of code. Does this mean I'm cool enough to be in your club?

> Does this mean I'm cool enough to be in your club?

If you have to ask, then the answer is no. I don’t make the rules.

This is the problem with any kind of documentation; while you can write the highest quality, meticulous, most obvious and clearest prose, it's moot if nobody reads it.

And nobody reads it because there's so much of it and there's no clear starting point. People just want the summary of what they're looking for.

I started to learn Java almost 20 years ago, we had a text book and everything. After the first two chapters, I learned how to google and instead of reading everything, just find what I need. I never went in-depth with reading because... it's mostly useless knowledge that quickly becomes outdated.

Nah, we have documentation with a clear starting point - there is index page with most common topics, "new user" page with links to what new user should read, and some error messages actually contain wiki links to pages with instructions.

And yet we still have people who don't read documentation.

With commit messages, there is a very clear starting point: the commit message for the commit that last touched the line of code you're looking at with git blame, which is my standard solution for finding out the reasoning behind any piece of code I don't quite understand. Only works for projects that don't destroy their history with squashes or otherwise write uninsightful commit messages (e.g. "fix bug").

Counter point - Engineering systems which require constant overriding of basic human nature therefore requiring making significant effort on the regular to avoid mistakes is bad engineering.

I'd hate to say that laziness makes a person an incompetent developer. Often my problems stem from an excess of sincere hard work and rather than from laziness.

But if you don’t cater to the worst on your team you are often viewed as the problem

The "just do your damn job" retort presupposes that their job is to read the entire body of every git commit. That's the question - you can't just presuppose it.

Reply on news.ycombinator.com