Hacker News Reader

Hacker News

Comment by fusslo | Hacker News Reader

Full thread

fusslo

great commits are great. This is fantastic

As an aside, I'm tired of documenting:

- in code

- in commits

- in jira

- in confluence

- in daily standups

- in release notes

View on HN

- in Sharepoint

- in some random Google Doc owned by one person that has to give permission to each individual who needs to read it, even though it's something the entire Engineering department should have access to.

- in a GitHub Wiki that nobody even realizes exists

- in a separate git repo that exists for just documentation, but nobody has checked anything into for 2 years

sometimes I wonder: If I didn't need to update 6 things, get approval from two colleagues, and justify the time to a scrum master watching how many tasks I complete every 2 weeks... would I write more meaningful documentation?

The code and commit documentation are about different things. One is about what this thing is, the other is about what is changing.

But then, jira is about what is changing, confluence is about what is changing, standups are about what is changing (oh, but this is doing them wrong), and release notes are about what is changing. So your complaint is completely reasonable, just the first item shouldn't be there.

I dont think Ive worked at a company that used commit messages to record what is changing.

Im not saying that I am disagreeing with you on that point. I’m just sharing my experience

We tend to rely on the diff and PR for the ‘what is changing’

The PR doesnt list the commit messages anyway, just the last commit message and the PR description

We add links to jira/confluence a lot in code to give direct access to the dev. Commits are tied to features or bugfixes

So effectively commit messages are not useful anymore

The only one that might be useful is the merge commit message

Again, not disagreeing, just complaining lol

You also get what is changing by doing "git diff", and often, it is self explanatory, especially if you have already commented in code why you did what you did.

For example:

  - code: MAX_SIZE=1024 // maximum size the backend supports
  - commit: limit the size to 1024, as it is the maximum the backend supports
  - jira: fixed the problem by limiting the size to 1024, as it is the maximum the backend supports
  - confluence: do not exceed 1024, as it is the maximum size the backend supports
  - standup: I set the maximum size to 1024, as it is the maximum the backend supports
  - release note: Maximum size set to 1024, as it is the maximum the backend supports

This is all redundant. I used a simple example for the sake of brevity, and one-liners are reasonable in every case, but the problem is when you are expected to write a wall of text every time, when in reality, there is everything you need in the code.

I'm generally wary of code comments. They tend to rot; people change the code around them but then forget to update the comments. They also take up valuable screen real estate. I'd mostly rather be reading code than comments, and I can see more context when there are fewer comments.

If a comment truly is necessary, it should explain why the code is doing something tricky, unusual, or unexpected.

In your particular example, that comment is superfluous; the constant should just be called MAX_SUPPORTED_SIZE, or something similar, that describes it better and makes the comment redundant and unnecessary.

Otherwise I agree; there's so much redundancy in our work, it's silly...

As someone who's been 'the next guy' to people who share your opinion: I really disagree with your opinion

I am generally on the same opinion as you are. I dislike superfluous comments and documentation. In fact, I usually try not to read these as these can be deceiving.

But this is one of the few cases where I think comments are worthwhile. That is, as an out-of-band channel where you explain things that are not in the code base, that is not common knowledge to skilled programmers, and that is hard to express in other ways.

This is a simplified example, normally, one would say more than that. Something like "for historical reasons, the backend is configured with a size limit of 1024, larger messages may be dropped". This value may be the result of a conversation with someone from the backend team, and without this comment, a newcomer will have absolutely no idea about the why, even if his is a programming god. And there is no easy way to express that in code. "MAX_SUPPORTED_SIZE" without any context may be insufficient, as it may raise questions about why this limitation even though the software used for the backend shouldn't have this limit.

I don't think the value of comments is only on the trickiness of the code. Some code like bit twiddling hacks may be tricky, but these are the kind of things good programmers should know, or if they don't, learn. There are publicly available resources for that. But parts, even simple parts, that require domain knowledge, or worse, knowing specific people in the company definitely benefit from comments if code can't express it.

- in code: code-level context

- in commits: changeset-level context

- in jira: if you need to provide changeset-level context, point them to the MR/commit log

- in confluence: high-level documentation

- in daily standups: status update; if you need to provide changeset-level context, point them to the MR/commit log

- in release notes: generate automatically from commit log

IMO duplication in documentation should be treated the same as in code – it should be avoided as much as possible.

Agreed except for

> - in release notes: generate automatically from commit log

Release notes are for a completely different audience and should be custom-tailored to that audience. They also shouldn't include changes that were reverted or made redundant by later changes in the same release.

Sure, commits-as-change-log is better than no change log but still very very far from optimal.

Reply on news.ycombinator.com