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

181–190 of 238 posts

Re: On Comments in Code

#181

Post by baby »

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?

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

Re: On Comments in Code

#182

Post by baby »

pmoleri wrote: post #126
neolog wrote: post #116

Earlier quoted context omitted.

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.

It’s super useful, rarely, when things haven’t moved around or someone wrote a good commit msg.

Re: On Comments in Code

#183

Post by t-writescode »

chapliboy wrote: post #171

I use comments to break up a large block of code into smaller chunks to explain what is happening / where we are in the process. I used to be a firm believer in self documenting code, but that approach often led to a large number of functions that only get called once. So lately, I have been just putting a comment line where I otherwise would have refactored the code into a function, and I feel that it has made my co…

How has your testing been impacted? I usually write several functions to isolate code for testing.

Re: On Comments in Code

#184

Post by watt »

alerighi wrote: post #48
mpoteat wrote: post #10

On the contrary, I find standard JSDoc and its variants to be an excellent tool for internal documentation. With hovering support in modern editors, it allows context explanation in a very streamlined and human way. The author mentions for preconditions to just “read the code”. I consider this bad advice. If using an external library, would you rather hover over the method and see its conditions, or would you rather…

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…

what is "set point"? Is it a point that is a part of some kind of set? What's "point" - is it part of some kind of coordinates?

You are documenting _what_. To document _why_, you must explain why somebody would want to change the "set point" and what is the effect, and not in terms that "setA sets a", but the semantics of it. What does setting point accomplish? What are the circumstances when you want to do it? _WHY_ would somebody want to call this method? Make the room colder? Make the room hotter? That kind of thing.

Re: On Comments in Code

#185

Post by slavik81 »

_old_dude_ wrote: post #89
rrose wrote: post #62

Earlier quoted context omitted.

sure, but reusing an integer variable is never going to bring a 2% speedup. allocating a new variable of almost any type is not going to cause any performance issues, at least if it is allocated on the stack, and if the construction of the variable is particularly expensive, resetting it probably will be too. I would need to see a realistic example to believe that something like this would ever be a useful comment.

In a compiled language, this is true for a local variable in general, it costs nothing because the compiler uses a register for it (or at worst spill it on stack but the stack frame size is reserved once for all stack allocated variables when the function is called). The story is different, if the variable is captured by a closure/lambda, the current stack frame or part of it may be allocated on heap, leading to perf…

> the stack frame size is reserved once for all stack allocated variables when the function is called

Is there somewhere that's documented for LLVM? That's my expectation of what the final compiler output should be, but I read that the IR allocates every variable dynamically, and then they optimize away whatever they can. I haven't been able to figure out how or where it's guaranteed that all allocations will be coalesced.

I wouldn't normally worry about it, but I've talked to folks who don't believe me when I say it doesn't matter whether you declare an integer inside or outside of a loop. It would be nice to be able to explain exactly why it can never matter.

Re: On Comments in Code

#186

Post by OnlyMortal »

bombcar wrote: post #155
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…

// // 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.

Re: On Comments in Code

#187

Post by AlotOfReading »

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

I've seen this counterpoint brought up many times before, but I'm struggling to think of the last time I experienced it. Is it really a common problem for you?

Re: On Comments in Code

#188

Post by OnlyMortal »

I recall having to write a set of long comments to explain a rather complex routine. When it got to code review we discussed the routine and I made the remark that, if I had to explain the code I’d written, it was probably too complicated to start with. Re-wrote the code to be simpler for the sake of maintenance.

Re: On Comments in Code

#189

Post by aequitas »

pjerem wrote: post #104
teknopaul wrote: post #43

Earlier quoted context omitted.

nonsense. code is intended for a computer by definition.

No. Code is intended for your teammates. Compiled machine code is for your computer. If you were addressing a machine, you would be writing 0s and 1s, because o boy do the machine know how to execute those little ons & offs.

But you end up with compiled machine code by using a computer to compile your high level code into machine code. You tell that computer exactly how you want it to compile your code into machine code. So in the end the code still is for the computer first.

I can write a basic function in 10 different ways that basically do the same, but have bugs or small differences in side effects that might not be obvious to a human reader at first glance. Languages just lack the expressiveness to explain those nuances, hence comments.

Re: On Comments in Code

#190

Post by jdlshore »

watt wrote: post #184
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…

what is "set point"? Is it a point that is a part of some kind of set? What's "point" - is it part of some kind of coordinates? You are documenting _what_. To document _why_, you must explain why somebody would want to change the "set point" and what is the effect, and not in terms that "setA sets a", but the semantics of it. What does setting point accomplish? What are the circumstances when you want to do it? _WHY_…

You have to assume a certain amount of domain knowledge, or you end up explaining the entire universe.

In this case, "set point" is a well-understood term, and its purpose is similarly well-understood. [1] Although the team may wish to document it, the place to do so is in the team glossary (or other overview documentation), not in every function that uses it.

[1] http://faculty.washington.edu/brengelm/neut_zone/pg3.html

Post reply on HN