Politely Suggesting Improvements


Thanks to IBM dW and Seda Özses for fixing the code to which I linked in CGI is Okay, but Bad Code is Irresponsible. To their credit, the security flaw and the Perl 4 style code in the article have become much, much better—now it's good example code, which is what everyone in this process wants.

This sort of thing will happen again. Perhaps we can learn from this experience and handle it better next time.

What should you do the next time you see example code with a security flaw and/or clunky style?

  • Contact the author directly and privately.
  • Explain the security flaw and demonstrate how to fix it and it alone.
  • Expand further on stylistic issues (explaining that, although there is not complete agreement in the entire Perl 5 community over some stylistic issues, the dominant trends are fairly widely understood as something we can all call modern or enlightened Perl), revising the code as necessary.
  • Suggest that the Perl 5 community has many resources such as PerlMonks, Perl Mongers, and mailing lists full of people who can and will perform technical review on code.
  • Be polite.
  • ... if that does not work, publish an explanation and corrected code elsewhere.

Where possible, stick with the constraints of the article. For example, Ms. Özses's code has good reasons to use CGI instead of a Plack-capable module. Respect that. (Though where it's obvious that a CPAN module is far superior solution, such as in the case of CSV parsing, do recommend the module.)

We share a goal, that useful and usable and correct and secure and sufficiently elegant code is available. We do not have to write the same code nor the best possible code to achieve that goal, but...

... people who publish code examples have a responsibility to write good code.

... people who review and comment on code have a responsibility to be both accurate and polite.

To that end, I owe Ms. Özses an apology. However I intend neither personal attack nor insult in my writings here, I failed to live up to my personal standards of kindness and politeness in this case. She deserves much credit for taking the suggestions of various Perl 5 programmers despite unwarranted criticisms.


Well said (but I personally feel that you're being too polite). I'm grateful that IBM continues to publish great articles on Perl, but -- putting things in content -- of Google were to publish example code that did not stand up to the community's standards, there would be several -- not just one -- posts provided constructive criticism.

now the real problem is... how to be polite... I find people are very sensitive to being told "there code sucks" but tbh, I haven't found a way to say it politely... I ended up in a flamewar because I started asking a question about an API, and had to explain why I was asking... and the answer was the API doesn't do what I need it to do, because it wasn't designed to do this... which ultimately devolved into each side saying "your code sucks" (btw pretty sure that render_file should not be calling create_file in a well designed API)

Modern Perl: The Book

cover image for Modern Perl: the book

The best Perl Programmers read Modern Perl: The Book.

sponsored by the How to Make a Smoothie guide



About this Entry

This page contains a single entry by chromatic published on February 2, 2011 10:22 AM.

The Method Keyword, take two was the previous entry in this blog.

How to Test the Method Keyword Patch is the next entry in this blog.

Find recent content on the main index or look in the archives to find all content.

Powered by the Perl programming language

what is programming?