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

51–60 of 68 posts

Re: Comment your damn code

#51

Post by lhnz »

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…

It's better to make a mistake in your thought process that can be caught by reading plain english than to write the code and realise the logic is wrong. However, I agree that comments that are completely banal should be removed in place of more interesting ones about the design decisions, performance characteristics, etc. (I however do start by writing comments explaining exactly the code I am about to create as I like to spot higher-level problems as early as possible.)

>> I saw fewer lines of comments until a fresh, new young team member joined

Young programmers and Knuth[0].

[0] http://en.wikipedia.org/wiki/Literate_programming

Re: Comment your damn code

#52

Post by tcgv »

Toshio wrote: post #7

Well, I disagree. Test-drive your damn code. The difference in positive impact will be a few orders of magnitude.

I agree with Toshio, well written TDD is the best low level spec you can get, and it is always up to date.

Re: Comment your damn code

#53

Post by klibertp »

So many comments already... Well, that's to be expected.

I agree with OP wholeheartedly, but I think he misses one obvious thing and that is the fact that commenting code is hard. Very, very hard, laborious and easy to get wrong. It hard even for people who are used to writing prose, like heavy bloggers for example. It's made even harder if you don't write in your native language, and "even harder" here means "almost impossible for many".

Unlike many programmers I enjoy writing, which should be visible to anyone who sees my comments here. I have quite a lot of background in writing various texts, from short stories to essays. Yet I find commenting - or rather - writing good comments in code very difficult. I think I can do this, I got praised for the comments at one time or another, mainly for their clarity (instead of sheer volume) which makes me extremely proud, but the fact is that I spend almost as much time on commenting the code as on writing it... Sometimes I write comments up front along with tests, to clarify my thoughts, sometimes I write them after coding something, but that does not change the difficulty at all.

I think the art of commenting code - and it is an art, no doubt about it - is comparable with debugging. As we all know, debugging something is twice as hard as coding it, so - by definition - if you code something to be as clever as you can you won't be able to debug it. Nor comment it properly.

And many of comments such as "I'm against commenting code" stems from this, I think - in many cases we're forced (in school, mostly) to code near the limit of our ability and then we're forced to comment; of course those comments are crap, but that's what we see for a very long time. Then we get used to it, we kind of expect comments to suck, and we think that they are a waste of time.

Not so. They are just very, very hard to master and there are very few people who would even try to teach about them. We can say whatever we want, but it won't change anything. We need to find those who really can write good comments and make them teach others...

After all this I have to admit that I doubt it's possible. Don Knuth tried with his "literate programming" idea and failed miserably. Among 25 programmers at my current work just one even knew the term, but didn't know any specifics, while all of them know who Knuth was. I don't mean to say it's hopeless... But it certainly seems like that to me.

Re: Comment your damn code

#54

Post by gte910h »

If you do the normal, please do not comment your code. If you did the strange, please explain it briefly, but maintainably.

If something is broken, link to something outside the code (aka, vendor bug).

Re: Comment your damn code

#55

Post by klibertp »

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 me who thinks that.

I cannot agree with you more. I didn't pay attention to giant ego of OP and I'm not qualified to measure how bad his English is (mine is certainly worse), but now that I think about it you're right - I still do believe that the author meant no harm, but the tone that he used won't help his message get across at all. :(

Re: Comment your damn code

#56

Post by peteretep »

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 deeply.

Comments like this allow a skim read for locating what you're after, and - as you identified - normally come in as I'm detailing the process, which means, doubleplusgood, you also get to see what I was thinking as I was writing the original code.

> One's code should be written in such a way as to inform a programmer maintaining the code to its purpose and utility

Almost. But you forgot "as quickly as possible".

> But it also means that comments should only be used when you're going against convention or doing something hack-ish on purpose.

I suggest that with experience, especially experience of being the curmudgeonly old senior dev on very mixed ability teams, with codebases sometimes a decade old, where the code is occasionally insane, you will start to be thankful of all clues the code can possible offer up as to why people do what they do.

Re: Comment your damn code

#57

Post by klibertp »

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…

"A comment, on the other hand, cannot be trusted."

Badly written comment cannot be trusted. Good comment will be changed much less frequently than code or tests and it will stay relevant and precise.

It's not impossible to write such comments... Just insanely difficult.

Re: Comment your damn code

#59

Post by peteretep »

augustl wrote: post #18

There's usually a large amount of comments and metadata relating to code that isn't present in the source files themselves, but in an external database: git blame path/to/file.txt I think this is one of the most underused tools in software development! I wish more editors had features like "show me the history of this class/function" etc.

And if you're really lucky, you can go find that commit in the Code Review tool...

Re: Comment your damn code

#60

Post by agentultra »

lhnz wrote: post #51
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…

It's better to make a mistake in your thought process that can be caught by reading plain english than to write the code and realise the logic is wrong. However, I agree that comments that are completely banal should be removed in place of more interesting ones about the design decisions, performance characteristics, etc. (I however do start by writing comments explaining exactly the code I am about to create as I li…

I love literate programming.

However literate programming isn't about commenting your source. It's about explaining your program in plain human language and presenting it in an almost essay style. A special program is run on your "literate" source which translates it to a set of source files that your compiler understands. It is not about writing verbose and excessive comments in your source code.

I don't mind if your approach is to write out pseudo-code or comments or what-have-you. My problem was that checking this stuff into the code-base wasn't a good idea. I don't suspect I changed the minds of the people I had to work with but they did remove the excess comments from the code before checking it in. That made reviewing their code much easier.

Post reply on HN