Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Comment your damn code

tech.collectedit.com

Post reply on HN
Print view View original

61–68 of 68 posts

Re: Comment your damn code

#61

Post by jasonlotito »

klibertp wrote: post #55
jasonlotito wrote: post #48

This comment leaped out at me: > what is going on in this icky mess This is a sign that your code is poor, and comments aren't going to help poor code. When you need to comment to overcome poor code, that's a sign your code needs help, not your comments. Thinking comments are going to solve this is a losing game. If this is the way you think, then you'll continue focusing on propping up poor code with comments. Comme…

"The assumption here is that it's easier to write comments well." And this assumption is clearly wrong. Just wanted to underline this. "It's quality, and quality takes time." ...and skill! "because writing clear comments is hard work" "But commenting your code well is a challenge. It's not easy, and should not be seen as trivial." "Well written comments take longer as well." So true. I'm glad there's someone beside m…

> I still do believe that the author meant no harm

His intentions were good, his delivery was poor. Ironically, the article itself makes for a great argument on why comments (here on HN) can be good, if you consider the article the code itself.

Of course, I'd argue that the comments here represent code review more than anything else.

Re: Comment your damn code

#62

Post by agentultra »

peteretep wrote: post #56
agentultra wrote: post #25

I used to work with someone who would start writing a function or module by writing their code as comments. # First we iterate over the directory and get a list of files to process ... # Then we process them This "pseudo-code" would then be filled in by the actual source code ei intended to write. And once ei was done the comments would stay in and be checked in for code review. Nothing was more tedious to read. It's…

I do this, and I'm a senior dev. I find it an absolute God-send when I come back to the code months or years afterwards. I am much, much faster at parsing and reading English than I am at code. When I'm coming back to some code for maintenance work, I am not normally trying to understand code deeply, I am usually trying to get a quick overview of it, and then locate a specific thing it's doing, to parse it more deepl…

You assume I'm young! How nice!

I read tonnes of code. I've formed my opinion by reading and reviewing tonnes of code. I'm cautious about jumping to conclusions.

In my experience the kind of code that requires comments to act as "guideposts," (if I've correctly interpreted your meaning) is suffering from symptoms of a larger problem: poor design. When I read code that comes from people who use this style I often find that their functions go on for ~70 LOC, use at least 3 levels of nesting, and are littered with comments to explain what is going on.

More often than not I was able to show them that they could break these procedures out into compose-able functions and drop the comments. With the right data-structures they could avoid excessive loops and conditionals. And with the right unit tests if they ever needed to change the implementation of a function they would know right away if they broke something. Suddenly they didn't need so many comments because their functions were That, of course, is the best case scenario. I've worked on a gnarly C++ web application that was more than a decade old and survived several attempts to port and extend it with Python. But you can deal with that too. Just try not to touch the legacy code. ;)

Re: Comment your damn code

#63

Post by bruceboughton »

peteretep wrote: post #56
agentultra wrote: post #25

I used to work with someone who would start writing a function or module by writing their code as comments. # First we iterate over the directory and get a list of files to process ... # Then we process them This "pseudo-code" would then be filled in by the actual source code ei intended to write. And once ei was done the comments would stay in and be checked in for code review. Nothing was more tedious to read. It's…

I do this, and I'm a senior dev. I find it an absolute God-send when I come back to the code months or years afterwards. I am much, much faster at parsing and reading English than I am at code. When I'm coming back to some code for maintenance work, I am not normally trying to understand code deeply, I am usually trying to get a quick overview of it, and then locate a specific thing it's doing, to parse it more deepl…

>> I am much, much faster at parsing and reading English than I am at code

Perhaps, but then you're parsing and reading what the comment says the code does, not what it actually does, today.

Re: Comment your damn code

#65

Post by peteretep »

bruceboughton wrote: post #63
peteretep wrote: post #56

Earlier quoted context omitted.

I do this, and I'm a senior dev. I find it an absolute God-send when I come back to the code months or years afterwards. I am much, much faster at parsing and reading English than I am at code. When I'm coming back to some code for maintenance work, I am not normally trying to understand code deeply, I am usually trying to get a quick overview of it, and then locate a specific thing it's doing, to parse it more deepl…

>> I am much, much faster at parsing and reading English than I am at code Perhaps, but then you're parsing and reading what the comment says the code does, not what it actually does, today.

Sure. When I'm trying to find a piece of code, that's a pretty good start.

Re: Comment your damn code

#66

Post by andrewcooke »

plorkyeran wrote: post #50
andrewcooke wrote: post #19

ok, so i wrote some code yesterday. i didn't write it expecting anyone to read it (i mean, not critically on hn), and it's not as good as i would like, but it has no comments (apart from at the top of the file explaining how to use the program). so, people who are saying "just comment it" - what would make a big difference to this code? https://github.com/andrewcooke/amcl/blob/master/amcl.py

PRESETS could use a brief explanation. Even after reading all of the code I'm not entirely clear on what it's being used for, and there's no hints to its purpose where it first appears.

thanks for the comments guys. i often work alone so it was interesting to check whether my standards match others. i agree on the points identified as being the weaker parts, and i'll try fixing things (not sure if that means re-writing or adding comments) when i have a moment.

[if this were paid work i hope i would have done something a little better, but that's easy to say...]

but also, in the context of this thread, maybe this shows that code doesn't need comments as terribly as some people seem to think.

my own opinion is that generally if you need a comment you should try to improve the code first, but that sometimes they can be useful. unfortunately that's a rather pragmatic approach that doesn't make for great blog posts or discussion flame wars...

Re: Comment your damn code

#67

Post by givan »

Write your damn code so that is easy to read and understand so it doesn't require comments.

Code comments are like subtitle for movies, when the code is chinese and you don't know chinese they are helpful.

Re: Comment your damn code

#68

Post by rvkennedy »

jasonlotito wrote: post #26
rvkennedy wrote: post #10

Why comments are important: they represent intention . A reasonable complex method can have a wide variety of inputs which the author can't be expected to have tested across the entire range of values. For example, if you have six boolean inputs, you have 2^6=64 possible combinations. If you have six integer inputs, you have roughly (4e9)^6=4e57 combinations, which is more than the number of atoms in the Earth. Expre…

Intention is all well and good, but imprecise. It also is not accurate to suggest that what is written is what is intended. One of the best ways I know of to describe intent is with tests. Not only do well written tests describe exactly what is being done, but it also tests to enforce this. There is no mistake about what it expected and intended. A comment, on the other hand, cannot be trusted. Ignoring the fact that…

There's no need to trust a comment, it simply tells you what the author was thinking, as best as s/he could express it. It's less imprecise than no comment at all. Suppose you have a very simple function that does something clear - reading the code you can tell what it does and how. And suppose that function is called from several hundred different contexts in the codebase, but one of those contexts causes an exception in your simple function.

You could "fix" it, with a code change. But what if your fix goes against the assumptions of some other context where the same function is called? A comment that describes what the function "should" do allows you to decide whether changing the function, or its caller, will be more in line with the design of the overall codebase. This is particularly true with mature codebases where thousands of tiny fixes and tweaks have accumulated over time. There's a corpus of learning about why the code ended up that way that even in-depth reading of individual functions might miss.

Tests are good, and to be encouraged. But using tests in place of comments is rather like answering a question with a question. Tests provide confidence, they do not provide understanding.

Of course, you could do an in-depth analysis of every function, in every context it's used, and how it interacts with its callers and callees. While you're doing that, the guys who commented their code will be moving onto the next challenge.

Post reply on HN