I have never cursed an author for having too many comments. There are many cursed developers out there after my long career.
You never lived through auto-javadoc?
On Comments in Code
41–50 of 238 posts
Re: On Comments in Code
#42Earlier quoted context omitted.
>Codes needs "why" comments, not "what" comments. Indeed. While there are exceptions, "what" comments will usually only add noise thus making things more difficult. This isn't necessary: // Total count int total_count = 0;
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.
To me it's actually faster and easier to read code instead. This is because i generally don't trust "what" comments - either I know the code already or I don't, and if I don't, then I don't trust the "what" comment fully, so I both have to parse "what" and code.
A "why" comment usually ages well, so I generally trust it and can use it to better parse the code and its intentions.
So I belong in the "what only for API methods" camp.
Re: On Comments in Code
#43Code 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.
nonsense. code is intended for a computer by definition.
Re: On Comments in Code
#44Important 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/
Re: On Comments in Code
#45Earlier 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.
You might as well be able to extract a method with a meaningful name then.
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.
Re: On Comments in Code
#46I have a personal rule: If I need a comment, it goes at the beginning of the function. This neatly groups the comment with the code it applies to. Occasionally I have to make a function "just" for this grouping purpose, but that's fine.
This is also my practice. Any code that is complicated enough to require a special comment is also complicated enough to be its own function.
Exactly my thinking. Very well said.
Re: On Comments in Code
#47Earlier quoted context omitted.
All code is literature intended exclusively for humans. Computers read machine instructions; they're incapable of reading code. Know your audience.
Humans wouldn't care so much about semicolons, but I do want the compiler to understand my code, too.
Have you seen decompiled code? That's all that compiler cares about, it is not pretty.
Re: On Comments in Code
#48On 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, /**
* change the temperature set point in use by the thermostat
*
* @param thermostat_ctx the thermostat context
* @param set_point the new set point
* @return SUCCESS on success, otherwise an error code
*/
error_t update_temperature_set_point(thermostat_ctx_t *thermostat_ctx, celsius_degree_t set_point);
thermostat_error_t update_temperature_set_point(thermostat_ctx_t \*thermostat_ctx, celsius_degree_t set_point);
Doc comments on the other hand really makes the code less readable, the increase the number of lines for most of the times not saying anything useful at all.
Re: On Comments in Code
#49The way I think about it is that comments needs to provide information that is both new and useful, where "new" and "useful" depend on the audience
http://jeremymikkola.com/posts/2021_03_21_useful_comments.ht...
Re: On Comments in Code
#50On 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…
That's more of an argument for them being overused, not for them being useless.