KohaCon10: An Argument for a project Coding Style

by ByWater Staff on Oct 28, 2010

Presented by Donovan Jones

Donovan argues that best practices and coding style are much the same thing, though best practices will include higher-level aspects like unit testing. What’s different about this talk and other best practices talks? No going to make any recommendations. The goal here is to make a case for having a style, and foster discussion on what that should be. The community shall decide.

Why have style? It requires less human cognition to extract information from the code. It’s easier to read, and thus easier to maintain, both by you and by your successor (even if that successor is yourself!). It’s communication with the future of the project.

Consistency is what’s important, not the rules themselves. Having an authoritative source is required to give people a mandate to make change and settle disagreements. We’re all on the same team here, and we need to think as a unified team.

Start small with what everyone can agree on. Add new rules when you can.

This problem comes up in most all major projects, and every one solves it differently. Again, the point is that they pick a set of rules, and stick to them.

As you create a standard, should it just apply to new code, or should you apply rules to all the previous code? Should the Release Manager reject patches that don’t conform to style? According to our current guidelines:

Don’t needlessly refactor code, __if it ain’t broke, don’t fix it__! Don’t waste time on changing style from someone else’s style to your’s! If you must refactor, make sure that the commit for the refactoring is completely separate from a bugfix, etc.

This helps make Git happier; you won’t be suppressing valuable history information (in git-blame) with style changes. If you’re doing fixes, don’t mix with actually coding changes.

Suggestions from Donovan:

1. Strict rules for new code
2. Subset of rules for old code (e.g. user warnings and use strict as required)
3. Open a bug for each fix

Reference: Perl Best Practices, by Damian Conway, ISBN: 0-596-00173-8.

This is not scripture. Local practices should override this book, but if you don’t have all the aspects covered therein, perhaps consider starting with those laid out, and expanding to meet your needs.

Tools to consider:

• Pre-commit Git hooks
• perltidy (sudo apt-get install perltidy)
• Perl::Critic (sudo apt-get install libperl-critic-perl)
• Editor configuration settings

[tag]kohacon10[/tag]

[Originally posted by Ian Walls]