What makes a comment "obnoxious"?

[papidave]

While perusing Perl::Critic::TODO, I found a request for the ability to detect "obnoxious" comments, where the description given is "Prohibit Excessive Hash Marks", e.g.:

   #### This is a loud comment ####

Being a bit anal-retentive on such matters, I try to make my code as elegant as possible, and would like to avoid behaviors that are "obnoxious". So I'd like to understand, what is obnoxious about a "loud" comment, if used in moderation? For context, I have only been working in Perl for about 7 years, but at this point it's my language of choice professionally, and it's not unusual for me to compose thousand-plus line files of documented code* as part of a multi-man-week project. In said projects, I delimit my functions as explicitly as possible so that the reader can scan them more quickly, e.g. :

###################################################

=head1 Foo method

The foo() method converts a fromitz into first-normal form,
and returns the result.  

=cut

sub foo
{
  my ( $fromitz, $word_order ) = @_;

  # ... code here ...

  return $result;
} # foo

###################################################

Are strings of hashmarks "obnoxious"? Or just when you embed them into the middle of a function, so it impedes the flow?

Update, 10-Sep-2007:

Not wanting to take myself too seriously on this, I have initiated a poll quest (Re: poll ideas quest 2007).

* Large files happen because of large object classes, since I try to stick to "one file, one module, one class".

* Update 22-Feb-08 - removed the prototype from my example. Please retest any code you have that uses it, as its behavior may have changed. :)

[shmem]

de gustibus non est disputandum.

"obnoxious" is what is obnoxious to you - the personal preferences of the authors of Perl::Critic, or of Damian Conway, need not be your own.

Your post makes me give another downvote to Perl::Critic. Enforcing a personal comment style and claiming it to be Best Practice? That's hubris at it's worst, and plain silly. Blech...

I read the title ever as "Damian Conway's Perl Best Practices", although I wished many of his advices were followed by every coder. But then there are some rules...

update: corrected inflexion and typo (missing s)... thanks blazar.

[adrianh]

Your post makes me give another downvote to Perl::Critic. Enforcing a personal comment style and claiming it to be Best Practice? That's hubris at it's worst, and plain silly. Blech...

Since all Perl::Critic policies can be switched on/off and have various different levels - and can be ignored on a case by case basis... I fail to see the "enforce"...

[shmem]

Well, there's no enforcement whatsoever in Perl::Critic, since not using it isn't illegal.

But changing "Enforcing a personal comment style" to "Making a personal comment style a policy" doesn't make things better, really.

[kyle]

To state the obvious, I think it's a matter of taste. Clearly, a series of hash marks in the middle of a function is obnoxious. I personally find hash marks as delimiters of sections of code to be eyesores also. If you're working with a file that's thousands of lines long, and you're breaking it up with comments, maybe you should be breaking it up into separate files. Even in a small file, I practically never scan through it in such a way that obvious breaks would be useful to me. I'm constantly searching (C-s in Emacs!) for what I'm looking for.

What I'd suggest is just to make yourself as consistent as possible. That way some maintenance programmer down the road will have an easy time reformatting your comments to taste. If your comments that I can't stand are regular enough, then I can probably take care of that in just a few minutes.

[Your Mother]

Comments are a form of design + writing. So they are impossible to programmatically correct/critique. What can be checked, and is the issue with a lot of Perl preferences, is the regularity and verbosity.

Perhaps checking POD:comment ratio and recommending (at a LOW level) more POD if there is little/none but lots of long-ish comments. Perhaps scanning for run-on comments. Do the comments seem to come in than 2 (some "block" style, and inline) styles in the code; probably 2 is plenty. Perhaps putting a spell checker, if it's installed, on the comments and providing low level verbosity about what might be misspelled. Verbose feedback is sometimes nice even if you don't agree with all of it.

I wasn't sure how I felt about Perl::Critic for a long time but the more I use it, the more I like it as a sort of automated code review + anal retentive, somewhat stupid, pair coding partner.

[snowhare]

They are by no means 'bad practice'. They are just a way to make subroutine start/end points visually obvious when scanning code. I use them routinely myself. If I were to find a good 'tree collapsing' editor for Perl, I would probably stop using them. But it is just someone's personal preference to declare them 'obnoxious'. It doesn't actually rise to the level of something that should be spit out by Perl::Critic as an issue.

Many programmers are obsessively anal retentive about details. It's a positive skill when applied to 'code correctness'. But it easily turns into pointless rules where simple personal preference is elevated into 'The Way It Is Done (tm)'.

[chargrill]

If I were to find a good 'tree collapsing' editor for Perl

Do you mean to tell me that there are editors that do not have this feature?

Even little vim has code folding, as soon as you discover how to best use it: install the perl-support plugin, and in it's documentation:

Syntax based folding can be enabled by adding the following lines to t
+he file
'~/.vim/syntax/perl.vim':                 
 
  let perl_fold=1
  let perl_fold_blocks=1

But back on topic, if you think the module author's idea of "obnoxious comments" is ridiculous (and you of course like everything else in Perl::Critic) - simply disable that policy in your .perlcriticrc file.

[snowhare]

Do you mean to tell me that there are editors that do not have this feature?

Some of us have been doing this long enough that 'new fangled tools' can be hard to keep up with. I "just looked" for a decent code collapsing editor "a few years ago". ;) At the time, I was disappointed with that new IDE, Eclipse. It was hard to install, was Java-centric, didn't have decent Perl support, and was too much trouble for small scripts. ;) (1)

I just gave the folding option for vim a try. I'll pass on that particular implementation of folding: It doesn't qualify as 'good' (or at least I couldn't figure out how to collapse/uncollapse stuff any other way than changing the 'foldlevel'). The other features in the Perl-Support plugin look very interesting.

Looking at SciTe and Geany (neither of which I had seen before today) I am initially impressed with their implementations of folding. Geany looks nice in general. My desktop work tools may be about to change.

Live and learn.

* 1 Yes. I know. My point was that it has been a few years since then. See the winking smilelies.

[philcrow]

Have you tried vim with folding? I really like that, but know that some people don't like vi.

Phil

[Anonymous Monk]

Even SciTe can do that!

[pemungkah]

I really should upload Test::Perl::Critic::Advisory to CPAN. It wraps all of the Perl::Critic tests in TODOs, so you still see the "failures" (and can fix them), but they don't cause the test suite to fail. And of course you can select your own priorities of what's a real problem and what isn't.

This also probably comes under "tests the author should run but the installer shouldn't have to".

However, back to the thread at hand. Perl::Critic can be valuable as a source of "hey, I should be sure I really wanted to do that" or "oops, we left a non-lexical filehandle in that code" information. I agree that blindly following every piece of its advice is no better than any other form of cargo-cult programming. But discarding the module because people are applying it wrong is, I think, overdoing it.

[talexb]

Hmm .. put me down for another downvote (not on your node) on the line of hashes. Although, I admit to being hypocritical on that, since ever source file I check into version control has something like

#!/usr/bin/perl -w
##********************************************************
## Copyright (c) 2004, 2005 That Company
## Copyright (c) 2006, 2007 This Company
##********************************************************
## $Id: SomeProgram,v 1.24 2007-08-23 13:37:05-04 talexb Exp $

at the top of each file. That's just what the company standard is -- but that's the only place I have lines of hashes. It's too noisy, but, as has been mentioned, it's a personal taste thing.

At least it wasn't a 'flower box' comment -- they were stylish in the late 70's, and not since then. Thank heavens -- they were truly ugly, and a pain to maintain.

[amarquis]

Flower box comments? Do you refer to this:

#############################################
#     I am a very difficult to maintain     #
#  comment, why did somebody do this?       #
#############################################

When I start maintaining somebody else's code I usually adopt their comment style for the sake of consistent code. If these kinds of comments are there, though, they go out the window. Even typing that was sort of a pain.

As said above, I think having a consistent pattern is more important than what that pattern actually is. If everything is the same, it's usually simple to go in and write a little script to make it look the way you want.

[talexb]

Yes, that's a flower box (shudder).

When I start maintaining somebody else's code I usually adopt their comment style for the sake of consistent code.

And that's an excellent idea. It's unbelievably tempting to go in and start making wholesale changes, but that's wrong for a couple of reasons:

• You just know you're going to break something (and tests may or may not catch that -- but why risk it? Oh, you don't have tests?) ;)
• It's not in the budget ("Um .. you've been reformatting comments for the last four days?")
• You may just end up confusing yourself further -- your brain's figured out how the old code worked, but now that it's in a new format, you have to learn it again. And if the original author comes back, a) they won't be happy, and b) it will take them longer to 'reload' what the codes does since it's not in 'their' format anymore.
And you've nailed down why -- it's most important to maintain consistency in a piece of code. A module that shows multiple styles is a module that's destined for failure -- it's a Tower of Babel thing.

[BrowserUk]

I have a considerable distaste for what I consider pointless comments, of which your lines of hashmarks are a prime example.

However, the best definition of 'obnoxious' I can think of, would be to codify my personal distastes into a module and then try and impose it upon the world.

The answer is simple, kick perl critic into the bit bucket from whence its like should never have been allowed to crawl out.

[saberworks]

Yes, I find large groups of hash marks completely annoying. Your subs should be separated by meaningful comments that detail what the function does, what it expects as arguments, and what it returns. If you have a decent syntax-highlighting editor, your pod comments should be enough to provide a very easy-to-see separation between your subs. If I'm scanning through subroutines, I just search for the word "sub" and hit next, next, next, etc.

[adrianh]

Your subs should be separated by meaningful comments that detail what the function does, what it expects as arguments, and what it returns

Or (even better!)

• The function name should reveal what the function does. If it doesn't change it.
• The name of the vars you rip out of @_ should reveal what the function takes. If they don't change them.

• The name of the variable you a return() should reveal what is being returned. If it doesn't update it.

(guess who is thoroughly sick of lying comments in legacy code :-)

[TStanley]

On the few occasions that I actually have to write programs these days, I usually put comments before anything that people might not understand, especially since I'm the only one in my company who uses Perl. And I try to keep it simple, like so:


##
## This is the comment
##
sub foo{ ... }

As most everyone else has mentioned, I believe that it is a matter of personal taste.

[gam3]

The practice that I have seen that I certainly find oboxious is:

########################
sub aSubRoutine {
########################
...
}

So I think that you on the right path with your thought about "obnoxious" comments being ones that break up the flow of the code.

[tubaandy]

I'm not a big fan of lots of octarands in comments, but that's my preference.

This discussion got me thinking, though. For lots of different professions, there is a style standard that is followed for publications. The American Chemical Society has a style standard, the American Psychological Association has a different one, and I'm sure that other professional entities do as well (I used ACS and APA as those are 2 I've worked in and I could think of off the top of my head, not to leave anyone else out.) While I think folks generally abide by "It's good to comment your code for other's benefit", isn't this more something that should be discussed and agreed to in the community (if that is important enough to act on)?

I do realize the difference between professional publications and scripting or programming. I don't really have an answer here, just wondering what others think.

Update:I looked up "octarand", and poqui is correct!

s/octarand/octothorpe/

We used this term in grad school, apparently I shouldn't have blindly believed my research advisor. ;) Mea culpa, and thanks poqui!

[papidave]

IMHO, the difference, I think, between professional publications and Perl programming is that the professional associations don't have a culture that states "TMTOWTDI". But that is precisely what makes this question interesting to me:
• Since any comment style that the reader can comprehend is "acceptable", we are clearly straining at gnats. This is ok, because the camel is on my desk, not in my coffee cup. :)
• If we all agree that this is a preference issue, the problem is equivalent to "What style is easiest to understand?" And, reading your preferences provides me with useful information about what people like/dislike.

Having said this, perhaps I need to initiate a poll...

-papidave

[BrowserUk]

The problem with assertions like "The American Chemical Society has a style standard, the American Psychological Association has a different one, ..." is the implicit assumption in that assertion that a) the chosen standard is the best possible for the purposes of the organisation involved; b) that everyone within the organisation agrees with the latter assertion.

I have never encountered any single organisation in which any single best practice, guideline or law was universally accepted by those within the organisation, much less those without. In every case, and I really do mean every case, that I am aware of, there are always...which makes this assertion the exception to the rule...exceptions to every rule, guideline, recommendation or law.

Yes. I know that last paragraph is a tautological nightmare, but read it slowly and think about it a while before dismissing it.

Until human intuition, compassion and judgement can be encapsulated into a piece of software, we (those of use lucky enough to live in societies that at least purport to support free democracy) will continue to rely upon the human intellect to discern right from wrong, good from bad, expedient from right. Any mechanism, process or system of law that discludes the possibility of exceptional incidence; mitigating circumstances; and the fallibility of human judgement; is dogmatic.

And dogma, is the root cause of all evil in world today. Just as it was yesterday. And will be tomorrow.

[kyle]

And dogma, is the root cause of all evil in world today.

Dogma is the root cause of all evil? That sounds pretty dogmatic to me.

This is starting to remind me of the teacher who said that someone who cannot understand and argue the opposite side of their own position is merely an irrational fanatical (or something like that). So what's the other side of that argument, I wonder.

Update: I think, actually, this comment is a bit more obnoxious than I intended. Sorry 'bout that. Add smileys to taste.

[tubaandy]

I appreciate what you're saying here (and I did read it slowly and carefully :) ). There's another off topic discussion about the need to standardize aspects of communication via refereed journals. In the ACS and APA examples, the reference standards allow anyone (who knows the standards) to easily go and look up the references, and are part of the rules to publish in journals governed by these bodies. (Theoretically, depending on your library, access to materials, you know.) Same thing applies to standardization of communication protocols, etc.

Again, these were examples that I had on the top of my head. Perl is great due to TIMTOWTDI, and there is no reason to change it, or to change comments. :)

[sgt]

Well personally I find that too many hash marks are distracting. They kind of attract my eye but not to whatever they might try to emphasize but rather to the hash marks themselves!

I normally use just one; two can appear when I want to block-comment a block of code and its comments.

But I do use Smart::Comments and I do hope these are not obnoxious by default ;)

cheers --stephan

[poqui]

I think part of the problem is the name of the symbol itself: "hashmarks" sounds vaguely obscene;
whereas "octothorpe" has an erudite sound.

Maybe the style wouldn't be so obnoxious if the name were nicer?

BTW, in my curiosity, I looked up tubaandy's "octarand" and couldn't find it anywhere; is any one else familiar with its use?

[Anonymous Monk]

"octothorpe" only sounds "erudite" to an idiot. The name came from someone who can't count to nine and who thinks appending a random football player's name is clever.