But I gather that this is the reason you mentioned the "first six paragraphs", because you were explicitly ignoring everything else.

Yes. That is a fair assessment. As with most of the other contrary points made in the thread, including your own, every point MadraghRua made in his last two paragraphs was addressed in my original post. I saw little purpose in further reiterating my counter arguments to those points, as I saw nothing in those last two paragraphs that in anyway diminished those counter arguments.

His premise is, that when some relatively expert coder constructs a piece of code, he should make an attempt to review the code he writes in the light of the possibility that the next guy that will view that code may not be as expert in the language being used. He, (the expert original coder), should then add comment cards to explain anything that he feels that the next guy might not understand.

I addressed this premise in my OP. Nothing in those last two paragraphs forms a counter argument, so there is nothing there to change my mind, and nothing that I can address other than through repetition.

However, since you seem bent on continuing the discussion, I'll have a go at reformulating the arguments in a way that I hope will lead you, and anyone else still interested enough to go through the exercise, to either produce cogent argument against my point of view, or to accept it.

What assumption should I make about the level of expertise of the guy that might follow me?

• Will he understand about context?
• Will he know when to use $array[ ... ] and when to use @array[ ... ]?
• Will he consider map too complex?
• Does he understand the concept of recursion?
• Will he understand

  if( !$cond1 && !$cond2 && !$cond3 ) { doit() )
  [download]

  perfectly, but somehow be flummoxed completely by

  doit() unless $cond1 or $cond2 or $cond3;
  [download]

  ?
• Will he consider regex some kind of scarey magic?
• While he consider this clear and maintainable?

  #! perl 
  use strict;
  
  my %data;
  while( my $line = <DATA> ) {
      chomp $line;
      my $position = index( $line, ':', );
      my $key = substr( $line, 0, $position );
      my $value = substr( $line, $position + 1 );
      $data{ $key } = $value;
  }
  my @unsorted_keys = keys %data;
  my @sorted_keys = sort @unsorted_keys;
  
  for( my $index = 0; $index <= ( scalar( @sorted_keys ) - 1 ); $index++
  + ) {
      my $key = $sorted_keys[ $index ];
      my $value = $data{ $key };
      print "$key : $value\n";
  }
  __DATA__
  a:1
  b:2
  c:3
  d:4
  e:5
  [download]

• Will he consider this, unmaintainable, deliberately obfuscated, arrogant, 'show off' code:

  #! perl -slw
  use strict;
  
  my %data = map{ /^(.+):(.+)$/; $1 => $2 } <DATA>;
  
  print "$_ : $data{ $_ }" for sort keys %data;
  
  __DATA__
  a:1
  b:2
  c:3
  d:4
  e:5
  [download]

  An interesting exercise for anyone convinced that comments help is to try and add comments to the above two snippets. If you feel like doing that and then posting the commented code, please do, because I will have great fun :)

Even if it was possible, and desirable, to agree some 'base level' of understanding of Perl syntax below which it was not necessary to explain in comments; it would never be possible to reach a universal agreement at where that barrier should be set.

And even if that barrier existed, requiring each programmer to come up with accurate, meaningful and useful comments to explain any construct or idiom that breaches that barrier, is simply ludicrous.

The answer to the problem of encountering code you do not understand, is to educate yourself.

Look it up or ask someone!

Take 5 minutes now to experiment with the construct until you do understand it, and then you will understand it forever. Avoiding it forever, because it confused you the first time you encountered it is silly.