Re^2: Why no comments?

[shmem]

Good commenting can:

What about s/Good commenting can:/Good coding can:/ ? And that's the main point.

• make you describe what is intended.
  
  That can, and should be done with code proper.
  
  
• make you to consider edge conditions and check that cases that need to be covered are covered. You should do that anyway, of course, but if you write it down it's more concrete.
  
  What is better than code which considers edge conditions, naming the conditions by proper set branches and variables? The requirements are (or should be) in the specs. Code is no place for that.
  
  
• require you to express and examine assumptions
  
  that is what we do all time along coding perl. Anything which can't be done that way needs to be cleared beforehand and laid down in the specs.
  
  
• justify and document the choice of algorithm or method.
  
  The choice of algorithm is done per knowledge. Now, you wouldn't document your knowledge in any (every?) piece of code you write, would you? Algorithms can be named, if they have a name. If they work out to the specs, that's fine. If they don't, they are changed, and describing the "why and whence and how" sayings doesn't add anything to the comprehensiveness of the code. The code should be written to be comprehensive in the first place.
  
  
• leave notes on things which were not obvious when you worked out what needed to be done or how to do it
  
  This is the only reasonable item in the list - quoting Kernighan: "Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it."
  
  Teaching perl, the first code samples of your pupils are like that:

  open my $h, '>', $file # try to open a file
      or die "Can't open '$file' for writing: $!\n"; # if that fails, te
  +rminate with a message
  while(<$fh>) {         # reading a line via <$fh> assigns per default 
  +to $_
      s/foo/bar/;        # s/// operates per default on $_
  }
  

  That's okay, since they want to remember what they have learned. Maintaining code and refactoring is a totally different issue. If you do that, you have to toss around code, and having comments piggyback is - piggyback, and a burden. If every EXPR is written properly; if every STATEMENT is clearly written; if every BLOCK defining a SCOPE containing STATEMENTS which are comprehensible on their own, or as part of the enclosing PACKAGE, or APPLICATION to which they apply, everything is fine.

I choose to code in perl (also ;-) because that way I have a wealth of expressions at hand which makes - or could make, if I work up to my level of experience - the code self-explanatory. And that's the goal. Anything below that can only be badly mended with comments. They are workarounds. Your program is a technical paper, which should be readable on its own by technicians of the same craft, but not necessarily for pupils (unless you are a teacher) or laymen. Those technicians which can't need teaching (by themselves, or training by somebody else), and that fact cannot be mended with comments either.