I have some experience in this area, starting from
the time I wrote On Coding Standards and Code Reviews.
I think a top twenty list is a good idea because many
folks are turned off by very long lists.
However, the top twenty list should focus on things
that matter -- not trivia or dogma.
Unfortunately, your list seems to focus on things
I would describe as "trivia". Indeed, most of your
list could be covered by a single point: "Agree upon a coherent layout style and automate it".
Here's my attempt at a top twenty list:
- Correctness, simplicity and clarity come first.
- Avoid unnecessary cleverness. If you must rely on cleverness, encapsulate and comment it.
- Avoid duplication (DRY).
- Coupling and Cohesion. Systems should be designed as a set of cohesive modules as loosely coupled as is reasonably feasible.
- Data hiding. Minimize the exposure of implementation details.
- Minimize the scope of variables, pragmas, etc..
- Establish a rational error handling policy and follow it strictly.
- Interfaces matter. Once an interface becomes widely used, changing it becomes practically impossible (just about anything else can be fixed in a later release). Design the module's interface first.
- Design interfaces that are: consistent; easy to use correctly; hard to use incorrectly; easy to read, maintain and extend; clearly documented; appropriate to your audience. Be sufficient, not complete; it is easier to add a new feature than to remove a mis-feature.
- Write components that are testable in isolation.
- The result of every file operation or API call or external command should be checked, and unexpected results handled.
- Use descriptive, explanatory, consistent and regular names.
- Avoid magic numbers.
- Don't optimize prematurely. Benchmark before you optimize. Comment why you are optimizing.
- Agree upon a coherent layout style and automate it.
- Adopt a policy of zero tolerance for warnings and errors. Tools such as Perl::Tidy and Perl::Critic can help here.
- Commenting: prefer to make the code obvious; don't belabor the obvious; comments describe what and why not how.
- Separate user vs maintainer documentation.
- Use a revision control system and single-step automated build/test.
- "Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live" (Damian Conway)
Rather than the standards police enforcing a standard
on a team, I think it is better to 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, 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.
-
Are you posting in the right place? Check out Where do I post X? to know for sure.
-
Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
<code> <a> <b> <big>
<blockquote> <br /> <dd>
<dl> <dt> <em> <font>
<h1> <h2> <h3> <h4>
<h5> <h6> <hr /> <i>
<li> <nbsp> <ol> <p>
<small> <strike> <strong>
<sub> <sup> <table>
<td> <th> <tr> <tt>
<u> <ul>
-
Snippets of code should be wrapped in
<code> tags not
<pre> tags. In fact, <pre>
tags should generally be avoided. If they must
be used, extreme care should be
taken to ensure that their contents do not
have long lines (<70 chars), in order to prevent
horizontal scrolling (and possible janitor
intervention).
-
Want more info? How to link
or How to display code and escape characters
are good places to start.
|