Stop commenting your code just to say you did

57 点作者 bradt大约 11 年前

21 条评论

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.

评论 #7509783 未加载

评论 #7510818 未加载

评论 #7509756 未加载

评论 #7509721 未加载

millstone大约 11 年前

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. For example, my PHP is about ten years old; I had no idea that `__construct` is the constructor, and not just another function. But thanks to the "useless" comment, I do know that.3. They're helpful for programmers who aren't as comfortable in the problem domain. A line in a FFT implementation may be "obvious" to those skilled in harmonic analysis, but not the poor client programmer who is trying to figure out why the function is returning garbage output.4. They can be useful as a thing to search for when you need to navigate around.When deciding if I should write a comment or not, I ask myself a simple question: if I come back to this bit of code, will it be obvious why it’s been written this particular way? If my future self will be very thankful for an explanation, then it’s a no brainer, I write the comment.Note the assumption that the code will only be consumed by "my future self".Ever maintained someone else's under-commented or no-commented code? I'm sure the original programmer did not have any trouble with it, and will never know what he inflicted on his successors. Spend some time working in a comment desert, and you'll never complain about the rain.

评论 #7509942 未加载

评论 #7510041 未加载

Danieru大约 11 年前

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 deduct full documentation marks.This has led some people I know to go over their code before submission and add worthless comments. To them "documentation" is a separate step which occurs after you've written and tested everything. The whole situation is a shame.

评论 #7510227 未加载

评论 #7509653 未加载

评论 #7509757 未加载

ef4大约 11 年前

This is one of the reasons that programmers who haven't read much of other people's code are a liability. They're as lost as novelists who don't read books.The difference comes down to empathy: if you can get inside the head of your future readers, you'll know when to comment, and what to name that function, and how long the functions should be, etc...

评论 #7509726 未加载

SomeCallMeTim大约 11 年前

The example that he gives that I take issue with is the "Constructor" one in a JavaDoc comment.When using documentation tools, every undocumented function spews a warning. And that is as it should be. But some simple constructors don't have any functionality worth documenting.I code as if all warnings should be addressed, and that's true of my documentation generation. If a public function has no documentation, that should be considered an error that needs fixing. If the documentation is obvious, then so be it.That is the price you pay for reliably good documentation; without enabling those warnings you don't know when you've missed documenting an important function. And even sometimes the "obvious" is useful; I don't know how many ambiguous Boolean parameters I've seen where it wasn't clear what value "true" represented.

评论 #7509907 未加载

评论 #7509895 未加载

nghst大约 11 年前

I think the occasional "header" comment is useful, even in cases where the code is obvious, i.e.<pre><code> // do blah blah obvious_thing; obvious_thing; obvious_thing; obvious_thing; // do something else obvious_thing; obvious_thing; obvious_thing; obvious_thing; </code></pre> Even though none of the lines really need documentation, having the comment ensures that you can quickly jump in when you come back later.This is really useful in something like drawing code.

评论 #7509547 未加载

methodover大约 11 年前

I cannot recall a time in my career as a programmer where the inclusion of a comment has caused me serious problems.However, I can recall many, many times where I've read code that does something odd, and wished that there was some documentation explaining it.I've met many programmers who rarely comment and make points similar to those made in this article. It's an easy argument: code should be self-documenting. But I've seen too many programmers jump from "code should be self-documenting" to "I shall never use comments/docstrings."I feel like the problems outlined in the article are overstated. It really isn't a big deal when you read a comment that doesn't make sense, or is empty of content. It's a much bigger deal when you read strange code which really deserves documentation but there is no documentation.

yk大约 11 年前

Thing is, just like with code, you write good comments by throwing away bad ones. The writing of the bad ones is not optional.

raverbashing大约 11 年前

YesIf you write this: x = 1; // sets x to 1 I HATE YOUExplain the WHY not the WHATIt's the same crap with the Hungarian notation, where half MS didn't get how to do it properly. It's not the computing type, it's what the variable represents. Thank you, I know this is an int, the compiler knows it's an int. What I need to know is what this is counting/representing/etc

err4nt大约 11 年前

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 whatever programming language the task requires, and second in whatever language the programmer speaks natively."

评论 #7510051 未加载

dmckeon大约 11 年前

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.

whyme大约 11 年前

I'll suggest there's a missing ingredient here...I found I was able to eliminate many of my comments by asking myself if that someone whom might read my code would be better served with a unit test instead. I also found, however, that this needs to lead to an understanding that unit test are in fact a form of documentation and should be treated as such.

评论 #7510379 未加载

kephra大约 11 年前

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.

beshrkayali大约 11 年前

Not that I don't agree, sometimes unnecessary comments kind of make it a bit complicated to understand what's going on. BUT, an important point to mention is that coders write code in different styles and manners, there is no right and wrong when it comes to comments. Sometimes just seeing that comments exist (even if some lines are pointing the obvious) makes a difference to the inexperienced or to the new-comers. Not to mention that "obvious" here depends heavily on the experience of the developer with language, framework, or whatever they're using. I guess the person writing the code should at least get to write comments the way the like. You're a programmer, reading a couple of extra comments won't ruin your day, just skip it if it's obvious.

quackerhacker大约 11 年前

Comments in production code have always been a pet peeve of mine. I understand the OP's frustration on useless comments where the function clearly states enough in it's naming convention.I brought this up to one of my instructors before and he said that comment overhead is negligeble on bandwidth (I was referring to css and js commenting at the time), but I don't think that's true when you factor in mobile networks and when some teams comment every freaking line when naming convention and common sense should suffice.

评论 #7510395 未加载

icehawk219大约 11 年前

One of my guiding principles for code comments has always been "say why not what". If I can't figure out that what on my own then something is probably very wrong with the code. What I want to know is why you used a for() instead of a while() to iterate over an array or things like that. Comments that explain what you're doing I find to be cruft. I don't necessarily hate on them but I do find them unnecessary and unhelpful.

logfromblammo大约 11 年前

My current employer makes the useless code comments mandatory. They do not need to make sense or be useful; the requirement is that they exist. Fortunately, they pay me enough that I am not looking for other jobs over it.No, I'm looking elsewhere due to the many other aggravations that are not worth the salary.Not only are businesses training younger developers to do this, but they are training older developers to expect it. Of course it is going to bleed over into the real world.

评论 #7509750 未加载

apdinin大约 11 年前

I can agree with the seeming intention of the OP, but the analogy of adding labels to wires in an electrical box is problematic. How does having blank labels on wires equate to poor commenting?Good or bad, a comment says something about the code it's commenting (even if the code is self explanatory). A blank label says nothing about the wire.The better analogy might be having labels on wires that state the color of the wires -- red, blue, green, etc.

korzun大约 11 年前

To author, the constructor is not a function it's a method.I agree with useless comments but don't agree with blank 'constructor' method doc blocks that just say constructor as a filler.Since most of the methods will have params/returns and better description than a simple constructor, leaving constructor without any doc-block is kind of counter productive and silly.

jgrahamc大约 11 年前

Leaving comments in real life: <a href="http://blog.jgc.org/2011/11/leaving-comments-in-real-life.html" rel="nofollow">http://blog.jgc.org/2011/11/leaving-comments-in-real-life.ht...</a>

评论 #7510367 未加载

shearnie大约 11 年前

Equally frustrating are revision comments (usually for a big end-of-day commit) that go: "Committed changes".