use Perl

• I think it depends (Score:1)

  by dug (2501)

  When I'm reading other peoples code I generally like comments that explain non-obvious algorithms, or places where the author hit a snag or bug and is alerting future maintainers.

  I generally don't like comments that explain obvious or trivial code.

  I like to revisit my code after a couple of months and see if the comments still make sense. Lots of times I end up stripping them out or re-writing them.

  -- Douglas Hunter
• Re: (Score:1)

  by Aristotle (5147)

  Bad, if you ask me.

  Structuring code well, choosing identifiers carefully, and using whitespace generously makes code mostly self-explanatory. The reason why the code is there and how to use it should be documentation. Comments are for explaining non-obvious algorithms, for calling attention to lurking bugs, or other problems, and the like.

  Basically, the documentation should explain why the code is there, and the code should explain how it works. Comments are only for highlighting surprising points in th
  • Re: (Score:1)

    by Beatnik (493)

    There are large chunks refering to other documentation, changelogs and technical requirements. There are also the sections not explaining how the code works but why it is done like it is..
    • Re: (Score:1)

      by mary.poppins (3530)

      "There are also the sections not explaining how the code works but why it is done like it is.. "
      
      The key to good comments is to explain why, not how. Kudos. As previously mentioned, good code makes the "how" clear.