en:devmon:guidelines:20bestpractices
20 Best Practices
- 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. (see variables)
- 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. (see tidy)
- Adopt a policy of zero tolerance for warnings and errors. Tools such as Perl::Tidy and Perl::Critic can help here.(see tidy)
- 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 https://github.com/bonomani/devmon 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)
en/devmon/guidelines/20bestpractices.txt · Last modified: 2021/08/19 07:29 by adminw1k1