Hacker News Reader

Comment by augustl | Hacker News Reader

I wonder where the idea comes from that people that write code that's hard to understand, will write comments that are easy to understand.

View on HN

Good programmers sometimes have to do weird things.

Leaving a note about that weird thing is probably a good idea.

I agree with this, but I also think it's better if you can avoid the weird thing.

In my experience:

A novice programmer will just do the weird thing (no comments).

An intermediate programmer will spend twice as much time as they should, trying to think of an elegant solution, before doing the weird thing anyways (and maybe leaving a comment).

A good programmer will just do the weird thing, leave a comment, and move on.

I somewhat agree, except possibly for the "should". I think that trying to think of an elegant solution (and then accepting that you can't, where appropriate) is an important learning process. Of course this depends on context; spending time on learning is sometimes inappropriate.

I agree with that. Perhaps more accurate phrasing would be "more time than the seasoned developer would have". Part of getting to the third stage is learning those types of lessons during the second stage - which only comes with experience.

    -- NOTE
    -- This is called by the database-level DDL trigger.
    -- Do not drop it. Do not break it.

We don't have a dev/qa environment, and tend to be a bit... lax about change management. There are a few pieces of code that this is particularly unsuitable for.

    function f_soundex (p_in varchar2) return varchar2
    is
    -- [name of specific source file from one of our other systems]
    -- If the first (kept) letter has the same code as the following letter,
    -- a proper Soundex ignores that following letter. The [other system] soundex
    -- keeps it.

Sometimes it is necessary to do weird things for compatibility reasons.

    // See http://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=98335
    // Apparently, DestroyHandle doesn't get called properly when a control is disposed. Since this
    // makes Invoke() hang, we have to fix it.

Sometimes external libraries/frameworks have bugs to work around.

    /* Don't let things scope to the repeat block. Even when they aren't used, they
       make the end statement slow. read-record.i has strong scoping for the data
       tables, and everything else is lifted to procedure scope. */

Sometimes there are performance reasons for doing things in a particular slightly odd manner. Sometimes there are correctness reasons (as with a 9-line comment earlier in the same program as this last example).

Well, native language and programming languages aren't the same thing and you express yourself differently in them. That's basically a given.

But comments are most useful when they explain why something is being done, not what's being done. The latter is usually simple to work out with even the most hideous code. But if I don't know what you were trying to do or why you did something in a particular way, seeing what you did alone may not be all that helpful, especially when maintaining code.

But all too often, people who write hideous code sprinkle it with comments that merely explain what is done, at the lowest level.

Yes. The industry is full of hacks. I don't see how that's a problem with comments though. They're going to write hideous code with or without comments.

The problem is that comments visually bloat the code and make it harder to understand. Bad code with useless comments is worse than bad code with no comments. And that's not even counting comments that are out of date and misleading...

And bad code with good comments is more useful than bad code with no comments. It strikes me that replacing "comments" with "tests" in much of our thread would lead to the same outcome. I guess we're just going in circles on this one.

> The problem is that comments visually bloat the code and make it harder to understand.

That's a good reason to avoid breaking up logical blocks of code with comments.

Its not a good reason not to comment.

> Bad code with useless comments is worse than bad code with no comments.

That's a good reason to have code review (which includes review of comments) to ensure that there is neither bad code nor useless (including out of date or misleading) comments.

native language and programming languages aren't the same thing and you express yourself differently in them

Indeed. However, when developing software I'd expect that the responsibility is first to express yourself clearly in code and only second to express yourself in prose, which means if you're taking very much time to do the latter it's time that could be spent doing the former.

The idea is that if you do a little bit of the latter now, you will save yourself or someone else a lot of time doing the former later.

I think because most people find written english easier to produce than clean code.

Comments have certainly aided me enormously in navigating very large, sometimes crufty, codebases.

I don't mean this negatively, but in my experience as a high schooler and in college, the programming crowd tended to be lacking in written (communication) skills. This is certainly a huge blanket statement, but for younger programmers today I think the stereotype has at least some truth.

There are some people whose code I'd be terrified to maintain, if their code/comments are anything like their text messages.

Reply on news.ycombinator.com