Again, it's all a matter of taste, but

• # method: getExitCode()

  This just replicates the sub getExitCode { line.

• # Author: Logan logan@eng.somecompany.com

  Authorship is often mixed even within a script and becomes redundant as soon as the author moves on. Email id's change.

  In a corporate environment, contact information should be in terms of "ownership" (in the 'who is responsible for this code') rather than who actually coded it. In any case, this information is better located in source-control database where it can easily be viewed and aggregated with other such info rather than in the source where it becomes out of date.

• # Usage: $ahm->getExitCode();

  I understand that this is just a simple example, but I see no benefit in this line at all. It gives me no information not readily available two or three lines below.

  Even if the method takes parameters, these cannot easily be added to this line, and would need to be documented seperately.

• # return : int

  This might make some sense in a C program, though even then, the function prototype serves much better and is more likely to be correct and up-to-date. What's an "int" in Perl terms? 16-bits? 32-bits?

• # Gets the exit code from a process and returns it

  If the sub/method name is well chosen, as this appears to be, I see this as redundant.

• #------------------------------------------- x 2

  Ugg! A personal hate, not a bad as

  ############################################# or

  /*********************************************

  But not much better. My preference is for whitespace to black, but again its all personal (or corporate edict).

  Can you imagine reading your favorite novell if every paragraph started with

  #-------------------------------------------
  # method:  setSceneForSurpriseEnding()
  # Author: WilliamS@YeTheatre.Olde
  # Usage:  read->setTheSceneForSurpriseEnding()
  # return : SceneSet
  # Sets the scene for the surprise ending and returns it
  #-------------------------------------------
  [download]

  I hope you won't take my levity too seriously, it's just one nobodys opinion:)

When I first set about trying to understand a piece of code, I generally ignore the comments and have even written several macros to remove them. Too many times I have been coersed into believing them when they only reflected the orginators intentions and not his actions. This can happen easily enough from reading the variable names as I said elsewhere today, but generally the authors actions are more clearly indicated by the code than by comments which all too frequently become out of date and therefore worse than just redundant, they can be misleading.

Of course, a comment warning of an unusually conveluted algorithm or indicating where (for example) additional punctuation is critical to the correct interpretation of the code are necessary and helpful. I also find it helpful if the coder indicates why s/he did certain unusual or unituative things in a particular way. Beyond that, I generally feel that most comments in code are redundant and serve only to obscure the forest with trees.

An untypical, and probably unpopular opinion, but one I have arrived at through bitter experience.