Focus on what not how

README.textile

@@ -36,26 +36,35 @@ _Then we need to figure out how best to communicate with that user (again using
 
 h1. Evolution
 
-This document will evolve over time. At any point any team member can suggest a change, and if the team agrees then the change is adopted.
-_However, nobody is allowed to unilaterally ignore any aspect of this document_.
+This document will evolve over time. At any point any team member can suggest a change, and if the team agrees then the change is adopted. _However, nobody is allowed to unilaterally ignore any aspect of this document_.
+
+h1. General Principles
+
+* All technical work is undertaken in order to deliver something that our clients value. If we can't identify client value in something we are proposing, then we shouldn't be doing it. Focus on delivering a _continual stream_ of value to the client.
+* Use simplicity as the primary metric when evaluating competing options. Avoid complex options unless the benefits are demonstrably overwhelming.
+* Lean heavily on your tools to automate as much routine work as practical e.g.
+** Enforcing coding style guidelines
+** Catching common programming errors
+*** Judicious use of tools like FxCop[3] or NDepend[4] for detecting errors
+*** Richer languages (e.g. F#[5]) and/or more sophisticated compilers (e.g. Code Contracts[6]) for preventing errors
+*** Types are your friend (most of the time), as they enlist the compiler to come to your aid. 
+* Make it correct, make it clear, make it concise, make it fast. In that order.[7]
 
 h1. Some Concrete Guidelines
 
-What follows are some guidelines under the folowing headings:
+What follows are some guidelines under the following headings:
 
-* General
 * Requirements
 * Design
 * Review
-* Implementation
 * Documentation
 * Testing
 * Build/Deployment
 
 These headings are only there to make it easier to navigate the content: they do *not* imply that we are following a waterfall process.
 
 The guidelines have been further categorised 
-(idea stolen from "Framework Design Guidelines":http://www.amazon.co.uk/Framework-Design-Guidelines-Conventions-Development/dp/0321545613) into:
+(idea stolen from "Framework Design Guidelines"[8]) into:
 
 * Do
 ** Something that we feel is extremely important to do. 
@@ -70,21 +79,6 @@ The guidelines have been further categorised
 ** Something that we feel is extremely bad practice. 
 ** There will only be _very rare_ exceptions, and these need to be discussed by the _whole project team_.
 
-
-h2. General
-
-* DO
-** Use simplicity as the primary metric when evaluating competing options
-* CONSIDER
-** Automating repetitive tasks
-* AVOID
-** Complex solutions
-*** Only ignore this recommendation if the benefits are demonstrably overwhelming
-* DON'T
-** Repeat yourself!
-** Fix it if it ain't broke
-*** We only refactor code that we are actively working on, otherwise we live with the imperfections and tackle higher priority issues.
-
 h2. Requirements
 
 * DO
@@ -96,44 +90,49 @@ h2. Requirements
 h2. Design
 
 * DO
-** Follow SOLID:http://en.wikipedia.org/wiki/SOLID_(object-oriented_design) design principles
+** Follow SOLID[9] design principles
 * CONSIDER
-** Pursuing a functional approach - immutable types, "pure functions":http://en.wikipedia.org/wiki/Pure_function etc
 ** Asking for a design review at any point of working on a story
 *** Feel free to pair with another developer if that seems like a better way to get two heads involved.
+** Using composition before reaching for inheritance[10]
+** Using Value Objects[11] rather than primitive types[12].
+** Pursuing a functional approach - immutable types[13], "pure functions"[14] etc
+** Using declarative rather than imperative approaches, where possible, even if this means learning a new paradigm e.g. Rx[15]
 * AVOID
 ** Constructing invalid objects
-** Mutable objects
+** Low level threading constructs (threads, locks, wait handles etc). There is almost always a better, higher level abstraction.
+** Global state - examine all use of static types.
 * DON'T
+** Mix mutable state and lazy evaluation. You have been warned - don't come crying to me.
 
 h2. Review
 
 * DO
 ** Get a code review when you think you've finished implementation
-** Guide reviews using SOLID:http://en.wikipedia.org/wiki/SOLID_(object-oriented_design) principles
+** Guide reviews using SOLID[9] principles
 * CONSIDER
 ** Starting reviews from the unit tests
 *** Lack of unit tests is an immediate failure of the review
 *** A reviewer should be able to infer the single responsibility of a class from the test suite
 * AVOID
+** Focussing on style issues. These kinds of checks should be automated.
 * DON'T
-** Be fooled by self explanatory easy to read code - it isn't necessarily SOLID
+** Be fooled by self explanatory easy to read code - it isn't necessarily SOLID[9]
 
 h2. Documentation
 
 * DO
 ** Write self explanatory code
 ** Write readable unit tests
-** Document all major design decisions - one possible approach:http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
+** Document all major design decisions[16].
 ** Add a single sentence XML code comment to the top of classes you write or touch
 *** Being forced to describe the single responsibility of a class can be a useful design aid
 ** Add a project level README.md to explain the role of each project within the solution
-** Add one or more high level diagrams to "explain the big picture":http://www.codingthearchitecture.com/pages/book/start-with-the-big-picture.html
+** Add one or more high level diagrams to "explain the big picture"[17].
 * CONSIDER
 * AVOID
 * DON'T
 
-
 h2. Testing
 
 * DO
@@ -165,13 +164,32 @@ fn1. Simple Made Easy:http://www.infoq.com/presentations/Simple-Made-Easy-QCon-L
 
 fn2. Code as Design:http://www.developerdotstar.com/mag/articles/reeves_design_main.html
 
-fn3. Framework Design Guidelines:http://www.amazon.co.uk/Framework-Design-Guidelines-Conventions-Development/dp/0321545613
+fn3. FxCop:http://www.microsoft.com/en-us/download/details.aspx?id=6544
+
+fn4. NDepend:http://www.ndepend.com/
+
+fn5. F#:http://www.tryfsharp.org/
+
+fn6. Code Contracts:http://research.microsoft.com/en-us/projects/contracts/
+
+fn7. Immutability, Purity, and Referential Transparency:http://blogs.msdn.com/b/wesdyer/archive/2007/03/01/immutability-purity-and-referential-transparency.aspx
+
+fn8. Framework Design Guidelines:http://www.amazon.co.uk/Framework-Design-Guidelines-Conventions-Development/dp/0321545613
+
+fn9. SOLID::http://en.wikipedia.org/wiki/SOLID_(object-oriented_design)
+
+fn10. Composition over inheritance:http://en.wikipedia.org/wiki/Composition_over_inheritance
+
+fn11. Value Objects:http://www.infoq.com/presentations/Value-Objects-Dan-Bergh-Johnsson
+
+fn12. Primitive Obsession:http://c2.com/cgi/wiki?PrimitiveObsession
 
-fn4. Architecture Decision Records:http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
+fn13. Immutable Types:http://msdn.microsoft.com/en-us/library/hh297115(v=vs.100).aspx
 
-fn5. SOLID::http://en.wikipedia.org/wiki/SOLID_(object-oriented_design)
+fn14. Pure Functions:http://blogs.msdn.com/b/ericwhite/archive/2006/10/03/pure-functions.aspx
 
-fn6. Immutable Types:http://msdn.microsoft.com/en-us/library/hh297115(v=vs.100).aspx
+fn15. Reactive Extensions:http://www.introtorx.com/Content/v1.0.10621.0/01_WhyRx.html#WhyRx
 
-fn7. Pure Functions:http://blogs.msdn.com/b/ericwhite/archive/2006/10/03/pure-functions.aspx
+fn16. Architecture Decision Records:http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
 
+fn17. Start with the Big Picture:http://www.codingthearchitecture.com/pages/book/start-with-the-big-picture.html