I am being clubbed to death by PEP 8.

I've just read PEP 8 and am not impressed. There's too little substance, too many platitudes and stating of the obvious with gratuitous exclamation marks. For example:

• "Always make a priority of keeping the comments up-to-date when the code changes!"
• "When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!"

If PEP 8 is your primary concern, you don't have much to worry about. :)

A while back I wrote:

• On Coding Standards and Code Reviews
• Why Create Coding Standards and Perform Code Reviews?

Though we have specific coding standards for each language, our general coding standards document, similar to On Coding Standards and Code Reviews, has perhaps proved the most useful. Last night, for example, I used it to club some external contractors into fixing some basic issues with their code such as "The result of every file operation or API call or external command must be checked, and unexpected results handled". Things that matter, not trivia.

Generally, Perl has come out of our coding standards effort looking very good. In particular, Perl::Tidy and Perl::Critic have proved to be excellent tools, unmatched by the other languages. For Perl, all new code must successfully pass through our tailored versions of Perl::Tidy and Perl::Critic before code review. Doing this avoids wasting time during the review arguing about trivia, such as code layout.

With a tip of the hat to kaizen, I suggest you set up a wiki page and encourage all team members to add to it during a code review, or at any time, when they find something that could improve the coding standard. That is, you need to create a vibe of inclusiveness with everyone trying to improve the quality of the shared codebase, not individuals fighting the standards police. And with a focus on real world things that matter, not trivia or dogma. The coding standard should be a living document.

To some extent, what goes into your coding standard reflects the level of your programmers. We have few Perl experts, many Perl part-timers, and some external contractors, so the sort of things that crop up here during code review (and then get added to our wiki page) may be trivial and inappropriate for an environment chock-full of Perl experts. Nonetheless, they are relevant to us because they actually happened (often repeatedly). I list below a couple of items to give you a feel for the sort of things that have cropped up here:

• Protect against metachars with \Q and \E where appropriate. To illustrate, /\d+ $nodename \d+/ should be written as /\d+ \Q$nodename\E \d+/ if the intent is to match the literal $nodename because $nodename may contain regex metachars.
• The use statement is performed at compile time, so putting one inside a subroutine is confusing. If in doubt, put all use statements at the top of the file.

---

---

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		&
	<		&lt;
	>		&gt;
	[		&#91;
	]		&#93;

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.