Re: Code Maintainability

[doom]

I'm becoming convinced that comments in code are close to useless. The first and greatest problem with comments is that they don't alter the code's behaviour. When your code's wrong, you can tell from its (wrong) behaviour. But when your comments are wrong, you can only tell by comparing them to the code. And if you're parsing the code to test the comments, then the comments are basically worthless: you're having to read the code as though they aren't there anyway.

Even a stale comment tells you something about the code -- you know immediately that someone made a change from the original version there, and they did it very quickly, without thinking it through (or else the comment would've been fixed, also).

If you want to talk about code maintenance, revising comments (and documentation) is part of the job.

And I'm sorry if this sounds rude, but it's based on experience: You really don't want to work with people who think their fabulous code is so beautiful it doesn't need comments anywhere.

[tilly]

No you don't know that about comments. Approximately one line in 10 that we initially write is wrong. This is true for both comments and code. The difference is that the mistakes in the code tend to get caught and fixed, while mistakes in comments do not. So a wrong comment does not indicate that there was a change, because it could have always been wrong.

As for who I do and don't want to work with, I have had the displeasure of working with people who never comment, and of working with people who comment everything heavily. Of the two styles I far prefer no comments at all. The style that I personally like is very sparsely commented code that is written in such a way that the code itself stands as a comment.

For more details I strongly recommend reading the old thread starting at Re (tilly) 2 (disagree): Another commenting question,. In that thread I discuss in detail a piece of code that I just wrote, the commenting decisions that I made, and the reasons for my deciding what to comment, where and when. I no longer hold to quite that style, these days I'm inclined to write longer variable names than I was back then, but I haven't changed views by that much.

[doom]

I've never had to work with one of the legendary "comment every line" types -- it could be they don't get hired at the kind of places I've worked.

From skimming tilly's example here: [Text::xSV] I would summarize that he likes sparse, higher-level comments, but with very verbose error messages that actually function fairly well as substitutes for comments. At a glance it does seem that both variable names and sub names are a bit short, but then, they don't strike me as confusing. He also likes pod-at-the-bottom style which also comes recommended by Conway in his "Best Practices" (I'm a fan of interspersed-pod style, myself, but not so much that I'd insist it's the One True Way).

By the way: if the main objection to comments is that they tend to diverge from the code, what does one do about those rather infrequently run error messages? Don't they, too, tend to diverge from the code? And what about the the "=item" lists buried down in the pod?

Anyway, as it happens, I've written up a brief comment example: Re^5: Programming *is* much more than "just writing code". In summary: explaining a paragraph of code in english can speed skimming through the code, and hinting at how a line of code works can sometimes be a good idea.

[tilly]

My variable and function names are now longer because I found that I used to shorten them inconsistently.

Errors are tested in my unit tests. If the logic leading up to the error message is wrong, I should notice that there.

Errors in POD are an issue for manual review. I do not claim perfection, and my error rate there is higher than elsewhere. But knowing that, I know to focus more attention there and so can catch a lot of those bugs.

[GrandFather]

True, one wouldn't wish to work with people who think that. But I'd sure like to work with people who's code is so beautiful it doesn't need comments (at least not implementation comments - context comments are to be encouraged).