naming conventions

Un-Common Sense

Common Sense Isn’t, Especially for Code (Part 1 of 2)

Scott S NelsonLeave a comment

Most of these will seem obvious. If they aren’t, you’re welcome.

No property files in EARs or WARs

Placing property files in a deployment package defeats the purpose of being able to update configuration values without a deployment.

Also be sure that your code supports immediate updates through property files using mechanisms such as a cache that checks for last update or a re-load mechanism that can be fired by the property file change.

Use Naming Conventions

When creating new projects and packages, either follow existing naming conventions/patterns or raise the need for a change and refactor all of them.

Always Use Relative Paths

Should not require a mention as we all know it, but seems folks forget it frequently so this is a reminder.

Always Document

Projects must have a readme that explains how to use the project.

Scripts should have usage notes at the top of the script. Preferably, the script should also do parameter validation and print out usage notes on validation failure.

All Connections Need Timeout Set

If all calls can be managed to a singlet timeout value, set it using an application-server level configuration. If not, manage it on a per connection basis with a single property file external of the deployment archive (usually the EAR or WAR) containing the timeouts to allow for updates to timeouts without compilation.

(Link to Part 2)

Facebooktwitterredditlinkedinmail
© Scott S. Nelson
Iteration 0 will suck

Accept that iteration 0 will suck

Scott S NelsonLeave a comment

While the definition of technical debt is…

…the implied cost of additional rework caused by choosing an easy (limited) solution now instead of using a better approach that would take longer. (https://en.wikipedia.org/wiki/Technical_debt)

the original cause of some tech debt is a combination of optimism and ego while following a best practice that should be expanded on. The best practice is to always keep code in source control to preserve work product in the event of hardware failure or accidental deletion (or the proverbial bus accident/lottery fortune).

The expansion this practice requires to truly be best is to use either a repository naming convention or a branch naming convention to indicate that source is the first iteration. The lack of this naming convention for initial commits leads to acceptance and defensiveness of early approaches that will often benefit from major refactoring if not complete abandonment.

Developers frequently avoid major refactoring for many reasons. In mature systems it can be a very real risk to do so and should be approached cautiously. However, the dislike of refactoring often impacts very early work where such changes can (and should) be done with ease.

Whether it is ego, optimism, laziness, deadline pressure, or a combination of any or all of the common factors, using naming conventions that make it clear that refactoring or replacement is expected will help to prevent early tech debt that will  likely worsen over time.

The next level is to maintain and architecture decision log for the repository and require an entry to that log for any first iteration commits to reach a status where the code will be deployed. Reviewing these decisions periodically will help identify both intentional (assuming an exception log as well) and unintentional technical debt.

Facebooktwitterredditlinkedinmail
© Scott S. Nelson