4 ms·
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 wha
by marcosdumay 3y ago
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.
- fusslo 3y agoI 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
- GuB-42 3y agoYou 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.
- kelnos 3y agoI'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...
- fusslo 3y agoAs someone who's been 'the next guy' to people who share your opinion: I really disagree with your opinion
- GuB-42 3y agoI 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.