News for hackers. Stuff that matters.

A comment on Open source code with profanity in comments is statistically better. Parent comment

Re:Open source code with profanity in comments is statistica... by vezuchyy on Thursday July 06, 2023 @02:50PM (#36620908)
If you have a process where every commit is well documented, you don't need much comments since you can rely on whatever is your analogue for git blame. It's not a lack of comments, it's actually the opposite but aside from the code base.

When I worked at SAP where VCS for ABAP is ancient and has no analogue for git blame we had a practice of putting a SAP Note next to every code change, since some of the things that we had to implement are dictated by business/legislation, so you need a proper explanation from time to time. Without it, the code becomes unmaintainable.

[ Parent | on HN ]
Re:Open source code with profanity in comments is statistica... by ShadowBanThis01 on Thursday July 06, 2023 @02:56PM (#36621005)
That requires everyone to have access to the repo, and to wade through it looking for changes to the relevant area of code you're working in. That sucks.
[ Parent | on HN ]
Re:Open source code with profanity in comments is statistica... by tormeh on Thursday July 06, 2023 @03:32PM (#36621518)
In which situation would you not have access to the repo? I guess if it's a library or something, but libraries must always be documented in a different way to business code.
[ Parent | on HN ]
Re:Open source code with profanity in comments is statistica... by ShadowBanThis01 on Thursday July 06, 2023 @05:25PM (#36623294)
Maybe you're a contractor. Maybe it's legacy code that has simply been archived. Maybe the network is down. Maybe there was a bad migration.

Sidecars generally suck because they get lost.

[ Parent | on HN ]
Re:Open source code with profanity in comments is statistica... by cerved on Thursday July 06, 2023 @09:21PM (#36625774)
If that's the case, you have bigger problems than documentation
[ Parent | on HN ]
Re:Open source code with profanity in comments is statistica... by ShadowBanThis01 on Thursday July 06, 2023 @09:48PM (#36625974)
Like what?
[ Parent | on HN ]
Re:Open source code with profanity in comments is statistica... by josephg on Thursday July 06, 2023 @04:38PM (#36622596)
Relying on commits also fails as soon as feature branches start being squashed. And the comments in commits can’t be modified over time. You have to hope readers “git blame” the correct lines of your code.

Just use comments.

[ Parent | on HN ]
Re:Open source code with profanity in comments is statistica... by cerved on Thursday July 06, 2023 @09:16PM (#36625741)
Don't squash. If you insist on it, I can't imagine why you wouldn't squash the commit messages

You're not supposed to change commit messages.

The correct lines to blame are the ones right there, not exactly rocket science

[ Parent | on HN ]
Re:Open source code with profanity in comments is statistica... by josephg on Friday July 07, 2023 @01:58AM (#36627780)
If your git squash contains all the commit messages, it’s a pain to figure out which commit message refers to which line of code.

A comment goes right there. No tools needed. Mutable. Readable. Contextually in place. And you can even add comments while coding without waiting for the commit.

Is typing // really so much effort?

[ Parent | on HN ]
Re:Open source code with profanity in comments is statistica... by cerved on Friday July 07, 2023 @03:38AM (#36628477)
No it's not and neither is writing a proper commit message. That's why you do both, but most of it goes in the commit. Like in the Git project
[ Parent | on HN ]