Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Open source code with profanity in comments is statistically better

blog.desdelinux.net

Post reply on HN
Print view View original

131–140 of 221 posts

Re: Open source code with profanity in comments is statistically better

#131

Post by josephg »

ShadowBanThis01 wrote: post #89
vezuchyy wrote: post #84

Earlier quoted context omitted.

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…

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.

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.

Re: Open source code with profanity in comments is statistically better

#132

Post by ckdot2 »

IshKebab wrote: post #81
mr_00ff00 wrote: post #55

Earlier quoted context omitted.

Isn’t commented code no longer considered a good idea in most companies? I used to work for a bank and the policy is no comments unless absolutely necessary, because comments become out of date. Doxygen is the only real comments allowed.

No, that is stupid. People just don't want you to write comments like // Set foo to true foo = true; Somebody saw one too many comments like that and overreacted. As long as you a) don't write comments describing what is self evident from the code, and b) try to make the code as descriptive as possible, then it's fine. Comment away.

it's not always as simple as that. what if you once implemented some facade method to get data from database like "findProductById" and you comment it with "finds a product from database by it's ID". later on, someone (maybe you) replaced some deeper logic here, so the product might be fetched from some other source, depending on some configuration. in case you didn't even touch the facade file, will you remember to update the comment? most developers will not. this risk is ALWAYS present if the comment explains more than the nearby code. so a comment is only safe if it contains the same degree of information like the nearby code. in that case though the comment is redundant. comments only make sense if they explain the -why-, not the -what- or -how-.

Re: Open source code with profanity in comments is statistically better

#133

Post by 7thaccount »

flatline wrote: post #63
mr_00ff00 wrote: post #55

Earlier quoted context omitted.

Isn’t commented code no longer considered a good idea in most companies? I used to work for a bank and the policy is no comments unless absolutely necessary, because comments become out of date. Doxygen is the only real comments allowed.

It really depends on the comments. Best practice is to comment “why” something was done, not “what” is being done, or “how”. Every programmer can read code, most code should be pretty self-explanatory. But in any sufficiently complex routine, there are going to be some things that a programmer struggled to get working the first time, that they had to work around, or that was simply unintuitive. These should be commen…

Ever read a Fortran code base? I once worked with a vendor that had nearly zero documentation, but at least you could get source and it was very well commented. You could spend a few hours and actually learn what was going on. The comments helped get enough of an idea to where reading the code wasn't too bad. I don't think I would've had the patience to only read the code without some assistance in what I should be looking for.

Re: Open source code with profanity in comments is statistically better

#134

Post by hakunin »

josephg wrote: post #128
hakunin wrote: post #122

Earlier quoted context omitted.

Pasting again my 4 reasons to leave a code comment: 1. An odd business requirement (share the origin story) 2. It took research (summarize with links) 3. Multiple options were considered (justify decision) 4. Question in a code review (answer in a comment) And the article on how/what/why in code: https://max.engineer/maintainable-code

I’d also add: - The code is not self describing for some reason (eg duffs device, complex math, non obvious cases, etc) - The code is correct but it looks intuitively wrong. This comes up every few thousand lines for me, where some conditional looks redundant or twisted up for some reason - like maybe there’s weird choices to keep the borrow checker happy. I leave a note to myself because next time I read that code I…

I agree with this, and some of this does come up in code review questions (point #4). Sometimes you can already predict a question or predict a mistake someone is likely to make, especially knowing your colleagues/context. In those cases a preemptive comment makes sense, but only if you couldn't somehow define that mistake/misconception out of existence in the code itself.

Re: Open source code with profanity in comments is statistically better

#138

Post by koromak »

tsukikage wrote: post #135

"In 2018, Adam Farley, a contributor to the OpenJDK project, the presence of profanity in the source code." Someone accidentally a verb.

"As part of your study, reviewed and analyzed over 3800 open source code containing profanity in English and over 7600 profanity-free open source code on GitHub."

Wow, over 3800 code? Thats so many code! And its my study? Even better!

Re: Open source code with profanity in comments is statistically better

#139

Post by bsder »

bravetraveler wrote: post #82
flatline wrote: post #63

Earlier quoted context omitted.

It really depends on the comments. Best practice is to comment “why” something was done, not “what” is being done, or “how”. Every programmer can read code, most code should be pretty self-explanatory. But in any sufficiently complex routine, there are going to be some things that a programmer struggled to get working the first time, that they had to work around, or that was simply unintuitive. These should be commen…

"Why" is a really good way to put it, like you say - doing "What" just repeats something a novice, possibly even a layman, could distinguish. I tend to treat them like a strange hybrid of a story with editor's notes. Here's where we're going... but oh no! Something is in the way. We need this critical, but painful to acquire shovel. If I anticipate even the slightest bit of refactoring around it, I'm noting what devi…

> "Why" is a really good way to put it, like you say - doing "What" just repeats something a novice, possibly even a layman, could distinguish.

And "profanity" in code is almost by definition a "Why"-type comment.

You don't get upset and leave a profane comment unless you did a deep dive and realized the code does something absurdly horrible that took you far too long to figure out.

Re: Open source code with profanity in comments is statistically better

#140

Post by slily »

bravetraveler wrote: post #82
flatline wrote: post #63

Earlier quoted context omitted.

It really depends on the comments. Best practice is to comment “why” something was done, not “what” is being done, or “how”. Every programmer can read code, most code should be pretty self-explanatory. But in any sufficiently complex routine, there are going to be some things that a programmer struggled to get working the first time, that they had to work around, or that was simply unintuitive. These should be commen…

"Why" is a really good way to put it, like you say - doing "What" just repeats something a novice, possibly even a layman, could distinguish. I tend to treat them like a strange hybrid of a story with editor's notes. Here's where we're going... but oh no! Something is in the way. We need this critical, but painful to acquire shovel. If I anticipate even the slightest bit of refactoring around it, I'm noting what devi…

It depends on the domain. I would be cautious about assuming that concise comments explaining what is being done in a block of non-trivial code are unnecessary. I have seen too many people write code they assume to be trivial (after spending days/weeks/months/years developing necessary background knowledge to understand it) when it's not the case at all. Debugging errors in undocumented code that involves several complex/opaque structures, nested function calls, and external libraries is not fun when you can't tell what step is at fault due to side effects, internal computations etc. not being clearly visible.
Post reply on HN