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

221–230 of 238 posts

Re: On Comments in Code

#221

Post by benrbray »

rwallace wrote: post #212
dstick wrote: post #170

Earlier quoted context omitted.

Exactly. And then the question remains: why? Why hate comments so much? I never got that

I would conjecture that it has two components: 1. Ancestral memory of programming in languages like assembly or early Fortran where your code was going to be spaghetti because the language was capable of little else, so it had to be drenched in comments that would be unnecessary in a better language. 2. Overreaction to personal memory of overzealous professors who demanded assignments be drenched in excessive comment…

Related to #2, I'm still recovering from high school AP English. We had to meet quotas for a certain number of underlines / notes written in the margin per page. For the better part of a decade I haven't been able to pick up fiction without the feeling that I'm working through a textbook.

Re: On Comments in Code

#222

Post by jaywalk »

pjerem wrote: post #102
jaywalk wrote: post #4

Earlier quoted context omitted.

Code involves names of methods and variables which can greatly aid in understanding as well. I've always maintained that comments should only be in code to explain something that is not obvious. If you're calling the SaveUser function and passing in a new User object that you had just created, a comment of "Save the new User object" adds nothing but noise.

- Do you SaveUser to the database directly or do I have to somehow call something to validate the transaction ? - Once it’s saved, can I continue to use my User model or should I fetch the more complete one from the database ? - Does this even SaveUser to the database or on a temporary structure that will be fetched by our UserCreationBot ? - Does SaveUser checks if the username already exists or should I check mysel…

Check the code of the SaveUser method.

Re: On Comments in Code

#224

Post by nicoburns »

hackinthebochs wrote: post #153
ziml77 wrote: post #45

Earlier quoted context omitted.

Please no. Don't extract methods methods just to avoid using a comment. You end up making code more difficult to follow when you do that since you're now jumping somewhere else in the file and you're adding a lot of noise by having to pass the function's current state along as arguments to the new function.

>by having to pass the function's current state along as arguments to the new function. But then the state being read and mutated by a block of code is explicit. The alternative is having to inspect the code to determine if and what state is being manipulated. The more code in a functional unit, the harder this gets.

If you're mutating variables then I'd agree that it might be best to encapsulate that in a function. But I'd argue that except for performance sensitive code, that's bad practice. The vast majority of code I write has 95% immutable variables. So even in a large function they'll typically be at most one or two mutable variables to keep track of (and very often zero).

Re: On Comments in Code

#225

Post by nicoburns »

bostonsre wrote: post #109
nicoburns wrote: post #16

Earlier quoted context omitted.

I find it's often useful to put a 'what commment' on a block of a few (2-10) lines of code. Then you can skim through the function without reading every individual line of code.

I do something like this, but I write them as debug log statements so that you get the additional benefits from logging.

Yes, I've also done this in places. It works pretty well, although I wish I could get my syntax highlighter to de-emphasise these lines like it does with comments.

Re: On Comments in Code

#226

Post by bombcar »

OnlyMortal wrote: post #186
bombcar wrote: post #155

Earlier quoted context omitted.

// // Dear maintainer: // // Once you are done trying to 'optimize' this routine, // and have realized what a terrible mistake that was, // please increment the following counter as a warning // to the next guy: // // total_hours_wasted_here = 42 //

Not a bad idea.

My code would probably be better served by:

This place is a message… and part of a system of messages… pay attention to it!Sending this message was important to us. We considered ourselves to be a powerful culture.

This place is not a place of honor…no highly esteemed deed is commemorated here… nothing valued is here.

What is here is dangerous and repulsive to us. This message is a warning about danger.

The danger is in a particular location… it increases toward a center… the center of danger is here… of a particular size and shape, and below us.

Re: On Comments in Code

#227

Post by baby »

chriswarbo wrote: post #208
baby wrote: post #181

Earlier quoted context omitted.

It’s a dumb idea, because that content gets lost as soon as you move things around.

Counter-point: moving things around in a way which doesn't preserve history is a dumb idea. Moving/renaming a file? Commit the deletion and insertion together, preferably with no other changes (including to the contents of the file; commit those afterwards). In the best case, VC will treat this as a move and showing the history will include that of the old place/name. In the worst case, that history of file 'foo' wil…

> moving things around in a way which doesn't preserve history is a dumb idea

I don’t disagree with you but you can’t prevent it.

Re: On Comments in Code

#228

Post by watwut »

ozim wrote: post #31
watwut wrote: post #19

Earlier quoted context omitted.

To me the above quote says that author never worked with anything more complicated or more big then simple crud web app.

To me it says that author is perfectly aware that people are not updating Javadoc comments or normal comments as well.

Which is still better then no explanation nor minimal hint at all unless you are doing something simple.

Re: On Comments in Code

#229

Post by b3morales »

cush wrote: post #174
benrbray wrote: post #165

Earlier quoted context omitted.

Tests are useful, but the big reason that comments are useful is that they are co-located with the relevant code. At the moment, I don't know of any tools that allow you to 1) specify which lines of code are directly relevant to a particular test case, even when the surrounding code changes and 2) see a list of test cases related to the currently highlighted line. I'm sure it would be possible to build such a tool, b…

Until the code changes, then the comments are usually worse than nothing

For the kind of code comment we started this thread talking about (explaining why some simpler/more obvious process is not used), this seems vanishingly unlikely.

Re: On Comments in Code

#230

Post by ItsMonkk »

ChrisMarshallNY wrote: post #44

Important topic. Documentation, in general, could use all the help it can get. I wrote up a long piece on this[0]. No one will read it, because it's long. I've found that no one reads anything that is more than about a "7 minute read," these days. Part of my documentation problem, is that I can get too verbose. It's not a good thing. [0] https://littlegreenviper.com/miscellany/leaving-a-legacy/

One of the key things that I believe is that the world has gone to far in the metric direction. Metrics lead to things like fake reviews, teaching to the test, and SEO. The only way to avoid this is to put your trust into people that you believe have good signal to noise ratios.

While posting on HN I believe that your posts have good signal to noise ratios, so I will now henceforth go through your post history looking for quality content. This post was one such event. Because I viewed your content like this, length went from a cost to a value. I read the entire article(okay, I skimmed the code sections).

Love the blog. It made my skills as a developer better. Not much to add, a benefit of the verbosity.

Post reply on HN