C#, CLR, Documentation

Document your patterns

The importance of patterns should never be underestimated – something we all know and understand… but how do you document your patterns in your own code base – i.e. patterns that are created by the internal team and are specific to the current project. Some examples of internal patterns could be “the way you create anew page in the system” or “the way you hook up to our special data store”.

A lot of the time the dev team leaders implement a new pattern then tell everyone to “copy it” once they need to implement it again. So developers copy the pattern, and over time it dilutes – it changes, morphs into a new pattern. The senior people who created the pattern leave the company, the new people come on and ask how to do something (hook up to the special data store, create a new page etc), and somebody points them in the direction of the pattern… be it the original, and copied diluted version, nobody really knows – and before you know it you are using a bastardised half pattern that isn’t exactly true to the intentions of the original developer. Before long you have the old way, the new way, and a mixture of the two.

Self documenting code is very bad in this respect – sure peer reviews can help, but even the peer reviewers themselves may have used a diluted pattern or diluted.

The result: patterns and internal code practices/conventions must – simply must be documented. Template your patterns, create snippets and examples. Enforce them… new developers will 100% read old code to see how stuff works, and Murphy’s Law states that these new developers will 100% of the time read the single wrong implementation in the entire 1000000 lines of code… I know I do.

When a method is old, you deprecate it – you mark it with an attribute so that developers know they shouldn’t be doing this. This isn’t done often enough with patterns in code. In fact patterns in code aren’t often even marked as a pattern.

Patterns should be surrounded by comments marking them out, and maybe patterns should be deprecated using comments so future developers can easily get the latest thinking and direction from the codebase. Patterns should also list their original documentation location / template file etc so developers can see the original non diluted version (and even better – they can see the most up to date version).

Finally, make proper names for the patterns – that way was can search through code and see all the different ways they are used!