Ironically, his article does not allow commenting
“My Code is Self-Documenting”
61–70 of 100 posts
Re: “My Code is Self-Documenting”
#62Earlier quoted context omitted.
The thing is, if somebody forgets to update a unit test, it immediately becomes obvious. If somebody forgets to update a comment, it's very easy for no-one to notice until it's much too late. There's no way to automate that check. In terms of developer resources, the act of doing updating the comments is cheap, but the act of making sure it gets done (in a systematic way) is comparatively expensive.
To miss comments in the code, developer must be blind. Maybe you are telling us about sad story of external documentation?
This isn't true, especially when you're dealing with legacy code that is overcommented. Your brain will learn to tune them out.
Re: “My Code is Self-Documenting”
#63I find that the commonly touted opinion that comments should only reflect why, and avoid all duplication; is misguided. The only places where I will elaborate on why is where I can see obvious room for improvement but I'm still waiting for the bigger picture to stabilize, or I'm adding a dependency that I'm not really happy with. Otherwise my comments mostly express the intent of the code in regular prose and have to…
If your comments just say what the code does, they're redundant and unnecessary. Good comments explain things the code can't, like why you chose a particular algo, or why some piece of code needs to exist. Most code when written well requires no comments. Comments like yours, that repeat what the code does, I simply delete.
Like I said, I don't agree with that particular broken record; there is value in stating the intent of code in normal prose as documentation.
Re: “My Code is Self-Documenting”
#64This is an odd one for me, 90% of the time I wind up subconsciously ignoring comments that exist in code. It's almost as if I can't see them on the screen. I've been in at least one argument with a coworker where I realized I was ignoring the existence of the comment he was referencing a line above the code we were looking at. On the other side of that, I'm usually adding comments about what's going on all over the p…
I read code the way you would a book, constructing this model in my head. Comments to me are a big flashing warning sign saying "this is so important, we added extra comments". If the comments aren't really that important it will start hurting my ability to read and understand the code quickly. likewise, if you a comment I wrote, you better sit up and read because it's there for a very good reason. I'm of the opinion…
I agree that accurately reading code is important, but no amount of reading just code tell you why something was done.
For a contrived example, why does a specific function/class use an array instead of a dictionary/hash table? A comment explaining that the dictionary was 500x slower in tests could fix that.
I suspect that is exactly the kind of comments you would want someone to "sit up and read" but I didn't want to assume.
Re: “My Code is Self-Documenting”
#65Earlier quoted context omitted.
If you update code without updating the comments and it gets past review you have bigger problems than them being misleading. Good comments are dependent on good developers.
Good results of any kind are dependent on good developers.
Right, but the point is more that bad developers can ruin any good methodology.
Re: “My Code is Self-Documenting”
#66Earlier quoted context omitted.
LOL. Comments are not a part of the code. Good comments adds to readability, bad commenting style (e.g. enterprise style comments for everything) affects readability. Comments cannot add bugs to code. What you think about spaces?
> Good comments adds to readability I agree. I was talking about the _amount_ of comments. Extreme example: void foobar() { // iterate over the list foreach(var item in list) { // send it sender.send(item); } } I've seen a lot of comments like this. They don't add value. They distract. They must be removed. They also tell that the author didn't have a clear understanding why code comments should be written, so we may…
It's looks like top-to-bottom style of development: first, algorithm is written in text, then implemented in code. Kind of literate programming. Sometimes it helps, sometimes it not. Usually, this style is used right after the school, by inexperienced programmers incapable to keep algorithm in the head in parallel to development, or when experienced developer does his first steps in a new language.
Not a problem for me. Usually, I clear them out.
Re: “My Code is Self-Documenting”
#67In my experience the worst code that I have seen was the one with the most comments.
If your code is self-explaining, if you have a full test coverage that documents what the code does and how it should be used then the comments are completely useless unless you are publishing a library or an external API.
In my current job I am required to add this completely useless Java Doc / xml doc comments for an application on which only I am working on, that is far more clear than the rest of the codebase, with extensive test coverage and currently I have the same amount of LOC and comments.
It's a total and utter waste of my time and it decreases the productivity so much trying to read the code in the middle of the comments that I had to find a visual studio and Idea extension to hide the comments to avoid getting distracted by all that awful noise.
Needless to say that I completely disagree with the author of the article and I hope that people sooner rather than later will understand that the living documentation of the code is in the code itself and in the tests that, by definition, can't ever be out of sync like the comments.
Re: “My Code is Self-Documenting”
#68The biggest problem I have with comments is that they quickly fall out of sync with the code. The code gets updated but the comments stay the same. Now you have a situation worse than no comments: misleading comments. It sometimes happens with self-documenting code too, but only when someone refactors enough of the code so that the class or method no longer matches the original name.
I hear this all the time as to why comments are "bad" (and I'm not suggesting that's what _you_ are saying, btw). Comments need to be kept up-to-date with code changes. The same way unit tests are kept up-to-date, and everything else around your code is. Comments are no exception.
Unit tests fail when they are out of sync.
Guess what? An out of sync comment will never fail.
Re: “My Code is Self-Documenting”
#69Earlier quoted context omitted.
No, the reader must not need to read the function to understand how it works. The idea would be that the function names are so good that one does not need to read the function contents, right? But some things are complicated and may not be expressible with the function name alone. That's why people write comments. To help readers understand the code. Let's say I am implementing some algorithm. I may mention the perfo…
No. If I have a function and I need to understand _how_it works_, that is, how does it implement some algorithm, of course I have to read every single line of code to understand how it works! If the function is named "quicksort", for example, and I suspect it has a bug, I really have to read it to understand whether it implements the quicksort algorithm correctly.
I don't think starting a comment off with "No" is an effective tactic to convey your point or change someone else' mind.
It seems clear to me, as an impartial third party, that there are merits and drawbacks to both of your school's of thought on comments. "No" attempts to shutdown the discussion and makes it hard to discuss these.
Re: “My Code is Self-Documenting”
#70Earlier quoted context omitted.
I hear this all the time as to why comments are "bad" (and I'm not suggesting that's what _you_ are saying, btw). Comments need to be kept up-to-date with code changes. The same way unit tests are kept up-to-date, and everything else around your code is. Comments are no exception.
The thing is, if somebody forgets to update a unit test, it immediately becomes obvious. If somebody forgets to update a comment, it's very easy for no-one to notice until it's much too late. There's no way to automate that check. In terms of developer resources, the act of doing updating the comments is cheap, but the act of making sure it gets done (in a systematic way) is comparatively expensive.
So add comments to your code review process. This really isn't hard.
For example: python functions shall have a docstring unless trivial. For external api functions on a class, there must be at least one example. etc etc. Plus, this makes working in ipython really nice!