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

On Comments in Code

henrikwarne.com

Post reply on HN
Print view View original

121–130 of 238 posts

Re: On Comments in Code

#121

Post by simonw »

bentcorner wrote: post #114
simonw wrote: post #74

Earlier quoted context omitted.

I love having commentary like that around, but I prefer to keep it in either the commit message or (more frequently) in the issue thread linked to from the commit. That way I can use as much space as I like for it and the timestamps make it clear that it's historical commentary, not a description of how the code works right now.

One caveat with this method is that your source control system evolves and things get archived. Code is around forever but everything around it may change. 10 or 20 years from now your code may still be running, the issue system or the git commit log may not be.

I am fiercely protective of my issue tracker and source history for exactly that reason. I have tools that can grab a full backup should I ever switch to something else: https://datasette.io/tools/github-to-sqlite

Re: On Comments in Code

#122

Post by xaedes »

bregma wrote: post #29
aequitas wrote: post #2

Code is for computers to make them do exactly what you want them to do, comments are for your co-workers (and you) to make them understand what you actually meant to achieve.

All code is literature intended exclusively for humans. Computers read machine instructions; they're incapable of reading code. Know your audience.

By the powers of compilers computers got the ability to read code. To leverage their powers we need to write code which the computer (~ program, aka compiler) understands. I write code for the compiler to read and translate. And yea, also for humans. But not exclusively. The compiler is not a human. It is only made by humans, like the computer.

Re: On Comments in Code

#124

Post by austinsharp »

bostonsre wrote: post #107
Normal_gaussian wrote: post #87

Earlier quoted context omitted.

Absolutely. I worked a codebase that was littered with ticket numbers for a few years; many members of the team religiously added them but never read them. How do we know? Self hosted issue system and access logs. New starts would read a couple and that was it. A ticket is a really opaque way of showing something. If you click the issue you're now going through several tangentially related comments and a few MR back…

I wonder if there are jira integrations that would bring ticket info into the ide. Although, I hate jira and would definitely prefer good git commits.

IntelliJ lets you expand links from patterns, so if in our codebase there's a BUGREPORT-12345 link, it's blue and clickable and goes to jira.

Re: On Comments in Code

#125

Post by pmoleri »

macintux wrote: post #73
crazygringo wrote: post #65

Another use for comments: to document the strategies you tried and why they failed. In other words not just the "why" but the "why not". Many times I've gone back to code I'd written previously, it seemed overly complicated, I replaced it with a simpler version... that failed... that reminded me that was what I'd tried originally and then replaced it with the more complicated version for a good reason. So now I have…

I refer to this type of problem a lot when arguing comments are useful. No amount of code can document the code that isn’t there for a reason.

Or you can write tests for every single not there case. Just bringing it up, I usually write lots more comments than tests. I also encourage my teammates to add comments. The problem is when one can't really explain why the simpler approach didn't work. That requires more research just to write the comment, but I think it pays off really quick.

Re: On Comments in Code

#126

Post by pmoleri »

neolog wrote: post #116
simonw wrote: post #74

Earlier quoted context omitted.

I love having commentary like that around, but I prefer to keep it in either the commit message or (more frequently) in the issue thread linked to from the commit. That way I can use as much space as I like for it and the timestamps make it clear that it's historical commentary, not a description of how the code works right now.

Some people advocate putting lots of stuff into commit messages, which makes me think I'm missing something -- commit messages are much less visible/accessible than comments in my workflow, so I don't expect my commit message to be seen. Do you always read the whole git history of a file before editing it? What interface do you use for that?

VSCode git-lens. Mandatory extension. Either way, I think both are useful, although for documenting weird code I think code comments are more important. I the commit message you should explain why you change the code. In the code, why it works like that.

Re: On Comments in Code

#127

Post by [deleted] »

neolog wrote: post #116
simonw wrote: post #74

Earlier quoted context omitted.

I love having commentary like that around, but I prefer to keep it in either the commit message or (more frequently) in the issue thread linked to from the commit. That way I can use as much space as I like for it and the timestamps make it clear that it's historical commentary, not a description of how the code works right now.

Some people advocate putting lots of stuff into commit messages, which makes me think I'm missing something -- commit messages are much less visible/accessible than comments in my workflow, so I don't expect my commit message to be seen. Do you always read the whole git history of a file before editing it? What interface do you use for that?

[deleted]

Re: On Comments in Code

#128

Post by xwolfi »

ravenstine wrote: post #68
crazygringo wrote: post #63

> If you wonder what the method does, or what the valid input range for a parameter is, you are better off just reading the code to see what it does. I couldn't disagree more. I was recently programming a library where some parameters could be 0 or greater, some parameters necessarily greater than 0, some parameters could be Infinity, others couldn't... Similarly, if one parameter is set to zero than another paramete…

When I started out programming I was taught that the code should "document itself" and that comments were an anti-pattern to writing good code. It took me a few years realize how idiotic that was and deprogram myself. It's one of those things that sounds nice, but once you've moved beyond a certain level of complexity you realize how impractical it is. The fact is that "good code" is often in the eye of the beholder…

Yeah, while it's true that a misleading comment can cause more harm than no comment at all, saying code is the documentation is cheating

Either we admit we'll never budget maintaining the comments metadata on top of the code, and embrace that risk for the cost reduction it provides, or we do document for real and maintain and review and fix regularly at a cost.

But saying we dont need to do it because it s already done is a quick stunt that everyone saying it knows is dishonest.

Re: On Comments in Code

#129

Post by jakequade »

> I didn’t need comments if I wrote self-documenting code.

More than any other approach to coding (x-based-development etc), this has come up most frequently for me personally, and it astounds me how many people have this mentality.

Comments are a way to break out of whatever terse syntax your given language requires and speak directly to the developer. A single comment can house so much more context and insight the best-formatted code could ever hope for. When the only downside is some holier-than-thou idea of "I shouldn't be doing this" (despite the fact you clearly need to), I'm surprised so many people fall for this terrible mentality.

Re: On Comments in Code

#130

Post by xwolfi »

philosopher1234 wrote: post #86
alerighi wrote: post #48

Earlier quoted context omitted.

If the name of the function and the parameters are clear, documenting the code seems useless. Take this real example: /** * change the temperature set point in use by the thermostat * * @param ctx the thermostat context * @param sp the new set point in 0.1 celsius degrees * @return 0 on success, But we can change around the name of the parameters like this and use proper strict types: /** * change the temperature set…

Why are method names priveleged over comments? They're both text read for human understanding. Why must the full documentation/definition for a function fit into the length of a method? These are silly restrictions, and lead to worse code.

Because writing a(a,b) is not ok even if comments are great, so why not make the method name a clear enough verb that comments are often unnecessary.

The problem is that not everyone code under the same circumstance, even inside the same codebase: you have the new joiner that has to reverse engineer most of what he uses, the senior who did or touched enough that he doesnt even see the color code for comments, the rushing helper who need to fix a bug now or else and cant maintain comments or he'll miss the deadline, etc.

Comments are sacrified first, tests seconds, code clarity third, correctness in edge cases next, etc. Embracing the reality that we're going to have to deal with crap once in a while would solve a lot of frustration.

Post reply on HN