Stop commenting your code just to say you did • Hacker News Board

Re: Stop commenting your code just to say you did

#51

Post by swanson » Tue, Apr 01, 2014, 5:29 PM UTC

tetrep wrote: post #47

swanson wrote: post #24

Earlier quoted context omitted.

// don't use hardware acceleration canvas.enableHardwareAcceleration(true); Which is true? The comment is lie. Is this a bug? Was this changed for some reason? Should I remove the comment? Should I toggle the boolean? Why weren't we supposed to use HW acceleration? Why are we using it now? What changed? What value did the comment have in the first place?

>What value did the comment have in the first place? That comment is the only indicator that something may be wrong. Your next steps are the same as with any suspected bug, find out what the code is doing (seems obvious here) and then find out if that's what it should be doing. That comment, however, is a good example of a bad comment. In this particular scenario, it's very obvious what the code is doing, so the comm…

Nope. You should do

  volume = 5;

Or

  setVolumeLevel(5);

Re: Stop commenting your code just to say you did

#52

Post by mattfenwick » Tue, Apr 01, 2014, 5:30 PM UTC

millstone wrote: post #28

Don't listen to this guy. Copious comments are great. 1. They act as a easier-to-skim narrative of the code. You can often get an outline of a well-commented component by reading the comments alone, rather than by picking apart a language designed for machine consumption. Syntax highlighting makes this especially easy. 2. They're helpful for other programmers who may not be as comfortable in the language as you are.…

If "copious comments are great" is true -- does that mean we should write copious comments?

I'm talking about opportunity cost here -- the time spent writing comments is time not spent on the code, design, test, etc. So for me the question becomes what I should do to provide the max benefit for the least cost -- should I write comments, improve the design, fix up some code to eliminate special cases, test for corner cases?

Since it's an inherent trade-off, I don't see this as being an easy question to answer. Probably, there are multiple adequate answers.

Re: Stop commenting your code just to say you did

#53

Post by err4nt » Tue, Apr 01, 2014, 5:31 PM UTC

err4nt wrote: post #44

I'm beginning to believe that if code is simply a machine-interpretable codification of human expertise, then we should be able to express precisely what the code should be doing using written language as well. I've been turning this over in my head to figure out how it should look in practice, but I'm wholeheartedly believing the following statement is true: "All code should be composed in two languages: first in wh…

I guess an extension of what I mean is maybe we should write our comments in a way that a human could read a program like a set of how-to instructions, complete the same operations, and arrive at the same result interpreting your work in written language as the computer would arrive at running the code. In my way of thinking about things, code wouldn't be complete until it could be interpreted by man and machine equally.

This allows for the preservation of our human expertise by guaranteeing that any program can be translated in the future by another human reading the same written language into any other programming language (even if they can't understand your code). This could be important especially for some of the more exotic languages with sparse documentation today, imagine what it will be like trying to decipher these things in 200 years!

Re: Stop commenting your code just to say you did

#54

Post by wdewind » Tue, Apr 01, 2014, 5:32 PM UTC

fournm wrote: post #11

wdewind wrote: post #5

Earlier quoted context omitted.

Here's a better solution: function main() do_blah_blah(); do_something_else(); end function do_blah_blah() obvious_thing; obvious_thing; obvious_thing; obvious_thing; end etc..

This isn't always possible in every case--it's not too hard to imagine a lot of trivial assignment all going on at once, that isn't immediately obvious what it is or why on earth it exists. //really bad example, just something really repetitive function main() // set up month boundaries janStart = blah; janEnd = blah; // ... decStart = blah; decEnd = blah; end where it's not too hard to imagine many languages without…

Return an array or hash?

Re: Stop commenting your code just to say you did

#55

Post by glimcat » Tue, Apr 01, 2014, 5:33 PM UTC

tetrep wrote: post #47

swanson wrote: post #24

Earlier quoted context omitted.

// don't use hardware acceleration canvas.enableHardwareAcceleration(true); Which is true? The comment is lie. Is this a bug? Was this changed for some reason? Should I remove the comment? Should I toggle the boolean? Why weren't we supposed to use HW acceleration? Why are we using it now? What changed? What value did the comment have in the first place?

>What value did the comment have in the first place? That comment is the only indicator that something may be wrong. Your next steps are the same as with any suspected bug, find out what the code is doing (seems obvious here) and then find out if that's what it should be doing. That comment, however, is a good example of a bad comment. In this particular scenario, it's very obvious what the code is doing, so the comm…

> That comment, however, is a good example of a bad comment.

Yes, assuming there's not some contextual reason why hardware acceleration is obviously inappropriate. But even then, it would be much better to err on the side of "assume the next person to read it hasn't had their coffee yet."

Even something like "don't use hardware acceleration because compatibility issues" would be a better comment. You don't need an essay. But it should be both concise AND descriptive of the issue, not just normative or prescriptive.

Re: Stop commenting your code just to say you did

#56

Post by kephra » Tue, Apr 01, 2014, 5:34 PM UTC

I've learned coding in Forth, so my code is often creating a domain specific language to solve a class of problems, and Forth shadow pages caused the documentation to be roughly same size as the code itself. But I normally comment in manual style. So the comments in my code do not tell how it works internally, but how to use it, and they are extracted from the code to create a standard Unix roff manual page. I think the Perl community did a good job in constraining a documentation style that is useful for those who want to use a module.

There are seldom exceptions, where I actually comment the code itself. Those are clear warnings that this code is not trivial to understand for average programmers. E.g. my w3dig search engine implements a recursive descendent parser for the site description language, that is not always executed linear, but sometimes pushes a parser class instance together with a closure to a queue, for parallel execution of the spider.

Re: Stop commenting your code just to say you did

#57

Post by glimcat » Tue, Apr 01, 2014, 5:39 PM UTC

andrewSC wrote: post #40

freehunter wrote: post #35

Earlier quoted context omitted.

I've got some code that looks like //don't do this do.this(true) To me, that signifies that I know the way I'm doing it is wrong, but it works until I can figure out how to do it right. Yes, I would be a horrible collaborator on a project. Most hackers would be, for the definition of hackers meaning "people who do isomething because it works, not because it's good programming".

Maybe a better way to clarify it's not ideal is to make a TODO. So: // TODO: Find out a better way to do this do.this(true)

TODO statements should be conserved to actual pending tasks.

Code in this pattern is often a compromise, and may be found as contributory to future issues, but it probably didn't merit a follow-up task at the time of writing.

Re: Stop commenting your code just to say you did

#58

Post by msluyter » Tue, Apr 01, 2014, 5:46 PM UTC

swanson wrote: post #24

carsongross wrote: post #7

God forbid someone gets their thoughts together with comments outlining what a function is going to do and then fills in the code... Or, while deep in thought, someone taps out a bit of redundant commentary on a line or two of their code... Or someone needs a bit of natural language to provide an anchor in their code. The important thing here, I think we can all agree, is that we are smarter than that person.

// don't use hardware acceleration canvas.enableHardwareAcceleration(true); Which is true? The comment is lie. Is this a bug? Was this changed for some reason? Should I remove the comment? Should I toggle the boolean? Why weren't we supposed to use HW acceleration? Why are we using it now? What changed? What value did the comment have in the first place?

I think it may be possible for all of the following to be true:

1. Comments explaining the 'why' can be helpful.

2. However, due to their inherent DRY violation, comments may become out of sync with the code and impose maintenance costs.

3. The value of comments still outweighs their maintenance costs.

That is to say, an example of a misleading comment doesn't necessarily prove that comments are bad in general. The converse may also be true, however. I no longer have a strong stand on this issue. I try to generally go with whatever commenting style the project I'm on uses, though I also have been known to write the occasional long descriptive pre-amble.

Re: Stop commenting your code just to say you did

#59

Post by glimcat » Tue, Apr 01, 2014, 5:50 PM UTC

Danieru wrote: post #9

I suspect part of this is enforced by TA markers in university. When marking a TA isn't trying to understand the code, they just do not have time for that. So when evaluating the documentation or comments portion of the mark they just scroll through and see how much gray is on their screen. No marks are ever deducted for bad comments. The situation can get so silly I've had TAs complement my code and the design then…

My experience as a TA:

I never counted students off for comments, although I also never worked with a professor who had a policy of "All Code Must Be Commented Or Else." I don't think many professors did, at least not for upper-division classes. Perhaps related - most students didn't comment at all (I largely dealt with CS seniors).

Then we had a bunch of students get counted off for bugs, unimplemented features, or general weirdness in their code.

As a rule of thumb, the very few people who did comment got much better grades simply because I was allowed to give partial credit. If they at least commented what the heck they were trying to do and how, and why they thought it advanced the project - I could probably figure out what went wrong and award points accordingly.

You know that Tolstoy quote, "Happy families are all alike; every unhappy family is unhappy in its own way"?

It applies perfectly to bad code. Whether we're talking university or industry, having SOMETHING there so that your teammates or the senior developer on the team can figure out what you were TRYING to do is an enormous help.

Going comment-light is fine in a perfect world where you have concise, elegant code that works perfectly and is absolutely clear when you come back in six months and try to figure out how you structured the program and what role any particular snippet serves within the greater whole.

It's not a perfect world.

(At the same time - readability functions such that if you put a bunch of trash comments in, people reading your code will assume that most of the comments are trash. You can't just tick the box and expect that to be enough.)

Re: Stop commenting your code just to say you did

#60

Post by dmckeon » Tue, Apr 01, 2014, 5:58 PM UTC

Comment first: project the document instead of documenting the project. In other words, write the comments first, then write the code, then review and tidy up both the code and comments.

By writing the text first, you clarify the why before you write the how. You also capture the high-level view before you get down to the gnarly details, after which the high-level view can become a vague ghost of a memory.

Once that high-level view is left behind, many people become so immersed in the coding details that "introductory" material written after coding often begins with the esoteric details of the implementation of the central algorithm, and fails to mention what the tool/packages/code/app is for in the first place.

To put it another way, documenting is to code as foreplay is to sex. Both code and sex can be effective without comments or foreplay, for some values of effective, but they are more likely to be more pleasant and repeatable over time if people put in a little time and effort before rushing ahead to what they see as the most interesting parts.