From bd260cadf0ad23c96d8afa54df882f0116e2b5bb Mon Sep 17 00:00:00 2001 From: Nathan Evans Date: Thu, 8 Nov 2012 15:33:16 +0000 Subject: [PATCH 01/14] Added comments re. composition over inheritence, type inference, avoiding static types, adding namespace commenting. --- README.textile | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.textile b/README.textile index 36cba9d..a2c3f26 100644 --- a/README.textile +++ b/README.textile @@ -97,6 +97,8 @@ h2. Design * DO ** Follow SOLID:http://en.wikipedia.org/wiki/SOLID_(object-oriented_design) design principles +** Prefer composition over inheritence. +** Use type inference (var in C#) to aid refactoring in the long-term. Less files touched = cleaner changesets. * 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 @@ -104,6 +106,7 @@ h2. Design * AVOID ** Constructing invalid objects ** Mutable objects +** Static types where possible. Retrieve a single instance lifetime scope from an IoC container instead. * DON'T h2. Review @@ -130,6 +133,7 @@ h2. Documentation ** 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 * CONSIDER +** Adding an XML code comment for namespaces to describe their scope and responsibility. * AVOID * DON'T From b930e6efa820ec5b754d9850c5fa537c5e1411b6 Mon Sep 17 00:00:00 2001 From: Akash Chopra Date: Fri, 23 Nov 2012 14:42:00 +0000 Subject: [PATCH 02/14] Added General Principles section --- README.textile | 62 +++++++++++++++++++++++++++----------------------- 1 file changed, 33 insertions(+), 29 deletions(-) diff --git a/README.textile b/README.textile index 36cba9d..4daae9e 100644 --- a/README.textile +++ b/README.textile @@ -39,11 +39,23 @@ 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_. +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 as practical e.g. +** Enforcing coding style guidelines +** Catching common programming errors +*** Judicious use of tools like FxCop or NDepend for detecting errors +*** Better languages (e.g. F#) or compilers (e.g. Code Contracts) for preventing errors +*** Types are your friend (most of the time), as they enlist the compiler to come to your aid. Also, the more specific[4] they are, the better - avoid primitive types[5] where possible. +* Make it correct, make it clear, make it concise, make it fast. In that order.[3] + 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 @@ -55,7 +67,7 @@ What follows are some guidelines under the folowing headings: 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"[4]) into: * Do ** Something that we feel is extremely important to do. @@ -70,21 +82,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,9 +93,9 @@ h2. Requirements h2. Design * DO -** Follow SOLID:http://en.wikipedia.org/wiki/SOLID_(object-oriented_design) design principles +** Follow SOLID[5] design principles * CONSIDER -** Pursuing a functional approach - immutable types, "pure functions":http://en.wikipedia.org/wiki/Pure_function etc +** Pursuing a functional approach - immutable types[6], "pure functions"[7] 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. * AVOID @@ -110,7 +107,7 @@ 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[5] principles * CONSIDER ** Starting reviews from the unit tests *** Lack of unit tests is an immediate failure of the review @@ -124,16 +121,15 @@ 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[8]. ** 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"[9]. * CONSIDER * AVOID * DON'T - h2. Testing * DO @@ -165,13 +161,21 @@ 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. Immutability, Purity, and Referential Transparency:http://blogs.msdn.com/b/wesdyer/archive/2007/03/01/immutability-purity-and-referential-transparency.aspx + +fn4. Value Objects:http://www.infoq.com/presentations/Value-Objects-Dan-Bergh-Johnsson + +fn5. Primitive Obsession:http://c2.com/cgi/wiki?PrimitiveObsession + +fn6. Framework Design Guidelines:http://www.amazon.co.uk/Framework-Design-Guidelines-Conventions-Development/dp/0321545613 + +fn7. SOLID::http://en.wikipedia.org/wiki/SOLID_(object-oriented_design) -fn4. Architecture Decision Records:http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions +fn8. 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) +fn9. 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 +fn10. Architecture Decision Records:http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions -fn7. Pure Functions:http://blogs.msdn.com/b/ericwhite/archive/2006/10/03/pure-functions.aspx +fn11. Start with the Big Picture:http://www.codingthearchitecture.com/pages/book/start-with-the-big-picture.html From 2c8985c864f55e5c6095f1e7496c50473d8e90bd Mon Sep 17 00:00:00 2001 From: Akash Chopra Date: Fri, 23 Nov 2012 16:34:54 +0000 Subject: [PATCH 03/14] Extended guidelines --- README.textile | 68 ++++++++++++++++++++++++++++++-------------------- 1 file changed, 41 insertions(+), 27 deletions(-) diff --git a/README.textile b/README.textile index 4daae9e..a49cd4c 100644 --- a/README.textile +++ b/README.textile @@ -36,21 +36,19 @@ _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. +* 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 as practical e.g. +* 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 or NDepend for detecting errors -*** Better languages (e.g. F#) or compilers (e.g. Code Contracts) for preventing errors -*** Types are your friend (most of the time), as they enlist the compiler to come to your aid. Also, the more specific[4] they are, the better - avoid primitive types[5] where possible. -* Make it correct, make it clear, make it concise, make it fast. In that order.[3] +*** 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 @@ -59,7 +57,6 @@ What follows are some guidelines under the following headings: * Requirements * Design * Review -* Implementation * Documentation * Testing * Build/Deployment @@ -67,7 +64,7 @@ What follows are some guidelines under the following headings: 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"[4]) into: +(idea stolen from "Framework Design Guidelines"[8]) into: * Do ** Something that we feel is extremely important to do. @@ -93,39 +90,45 @@ h2. Requirements h2. Design * DO -** Follow SOLID[5] design principles +** Follow SOLID[9] design principles * CONSIDER -** Pursuing a functional approach - immutable types[6], "pure functions"[7] 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[5] 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[8]. +** 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"[9]. +** Add one or more high level diagrams to "explain the big picture"[17]. * CONSIDER * AVOID * DON'T @@ -161,21 +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. Immutability, Purity, and Referential Transparency:http://blogs.msdn.com/b/wesdyer/archive/2007/03/01/immutability-purity-and-referential-transparency.aspx +fn3. FxCop:http://www.microsoft.com/en-us/download/details.aspx?id=6544 -fn4. Value Objects:http://www.infoq.com/presentations/Value-Objects-Dan-Bergh-Johnsson +fn4. NDepend:http://www.ndepend.com/ -fn5. Primitive Obsession:http://c2.com/cgi/wiki?PrimitiveObsession +fn5. F#:http://www.tryfsharp.org/ -fn6. Framework Design Guidelines:http://www.amazon.co.uk/Framework-Design-Guidelines-Conventions-Development/dp/0321545613 +fn6. Code Contracts:http://research.microsoft.com/en-us/projects/contracts/ -fn7. SOLID::http://en.wikipedia.org/wiki/SOLID_(object-oriented_design) +fn7. Immutability, Purity, and Referential Transparency:http://blogs.msdn.com/b/wesdyer/archive/2007/03/01/immutability-purity-and-referential-transparency.aspx -fn8. Immutable Types:http://msdn.microsoft.com/en-us/library/hh297115(v=vs.100).aspx +fn8. Framework Design Guidelines:http://www.amazon.co.uk/Framework-Design-Guidelines-Conventions-Development/dp/0321545613 -fn9. Pure Functions:http://blogs.msdn.com/b/ericwhite/archive/2006/10/03/pure-functions.aspx +fn9. SOLID::http://en.wikipedia.org/wiki/SOLID_(object-oriented_design) -fn10. Architecture Decision Records:http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions +fn10. Composition over inheritance:http://en.wikipedia.org/wiki/Composition_over_inheritance -fn11. Start with the Big Picture:http://www.codingthearchitecture.com/pages/book/start-with-the-big-picture.html +fn11. Value Objects:http://www.infoq.com/presentations/Value-Objects-Dan-Bergh-Johnsson +fn12. Primitive Obsession:http://c2.com/cgi/wiki?PrimitiveObsession + +fn13. Immutable Types:http://msdn.microsoft.com/en-us/library/hh297115(v=vs.100).aspx + +fn14. Pure Functions:http://blogs.msdn.com/b/ericwhite/archive/2006/10/03/pure-functions.aspx + +fn15. Reactive Extensions:http://www.introtorx.com/Content/v1.0.10621.0/01_WhyRx.html#WhyRx + +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 \ No newline at end of file From c59f3c8519797f1e6cf1cb05be41cce553446363 Mon Sep 17 00:00:00 2001 From: Nathan Evans Date: Wed, 28 Nov 2012 14:45:53 +0000 Subject: [PATCH 04/14] Change block quote section at top to introduce as a manifesto. --- README.textile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.textile b/README.textile index a2c3f26..c82bf87 100644 --- a/README.textile +++ b/README.textile @@ -1,6 +1,7 @@ h1. The Pebble Way -bq. "Simple software that solves difficult problems" +bq. A manifesto for producing: +_"Simple software that solves difficult problems"_ -- pebble {code} website (2012) This document defines what we at pebble {code} believe is the correct way to develop .NET software. From 016048efc6c3b406f3271fb07228a028321e09f9 Mon Sep 17 00:00:00 2001 From: Nathan Evans Date: Wed, 28 Nov 2012 14:48:00 +0000 Subject: [PATCH 05/14] Change wording of introductory paragraphs. --- README.textile | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.textile b/README.textile index c82bf87..f1f5a73 100644 --- a/README.textile +++ b/README.textile @@ -4,19 +4,19 @@ bq. A manifesto for producing: _"Simple software that solves difficult problems"_ -- pebble {code} website (2012) -This document defines what we at pebble {code} believe is the correct way to develop .NET software. -It starts from the assumption that the team is smart, motivated and _passionate_ about software development. Therefore -it is not an attempt to prevent a weak team from causing damage; it is a set of guidelines that can: +Pebble {code} believe the correct way to develop .NET software starts from the assumption that the team +is smart, motivated and _passionate_ about software development. This manifesto is not an attempt to +prevent a weak team from causing damage; it is a set of guidelines that can: * Help smart people come up with the correct solutions to the problems they face whilst developing software. * Encourage creativity and risk-taking by providing a safety net that detects problems early and limits their impact. * Allow people to move between projects by reducing the learning curve to the bare minimum. -It is heavily based on the ideas in "Simple Made Easy"[1]. Make sure you have watched that video before proceeding with the rest of this document. +It is heavily based on the ideas presented by "Simple Made Easy"[1]. *Make sure you have watched that video before proceeding with the rest of this document.* -Firstly, all software development is a design activity[2], and simplicity lies at the heart of all principles and guidelines for software design. +All software development is a design activity[2], and simplicity lies at the heart of all principles and guidelines for software design. Rather than trying to list out everything that we believe we should be doing (which is an impossible task because the -correct approach is always context-dependent), _analyzing the problem from the perspective of simplicity can provide a +correct approach is always context-dependent), _analysing the problem from the perspective of simplicity can provide a way to arrive at the correct solution_. However, we typically conflate the meaning of "easy" and "simple", so the first step is to clearly differentiate the two terms so that we can have meaningful conversations: @@ -25,13 +25,13 @@ step is to clearly differentiate the two terms so that we can have meaningful co * Simplicity is often hard to achieve * Simple things are _always_ easy to use -Secondly, we are blind to a lot of the complexity because it is so familiar to us. Many of our current standard software +We are blind to a lot of the complexity because it is so familiar to us. Many of our current standard software development practices originated over 20 years ago, and are optimised to deal with far more onerous constraints (both in terms of hardware and software) than we face today. As a result, these practices often introduce significant accidental complexity into our solutions. _We need to be open to investigating the new approaches that will become dominant in the next decade_. -Thirdly, we need to be clear about who the user is, as they (*not* us) will judge our efforts. For a UI, it is the human interacting +We also need to be clear about who the user is, as they (*not* us) will judge our efforts. For a UI, it is the human interacting with it; for an API, it is the client application; for a component, it is the next programmer who needs to understand it, etc. _Then we need to figure out how best to communicate with that user (again using simplicity as a guide)_. From 65563bc2896ef55fa7f586e1e17d6aa2cb5dbd40 Mon Sep 17 00:00:00 2001 From: Nathan Evans Date: Wed, 28 Nov 2012 14:50:00 +0000 Subject: [PATCH 06/14] Normalise bullet points line endings to not terminate with a full stop symbol. --- README.textile | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/README.textile b/README.textile index f1f5a73..091f418 100644 --- a/README.textile +++ b/README.textile @@ -59,18 +59,17 @@ 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: * Do -** Something that we feel is extremely important to do. -** There will only be _very rare_ exceptions, and these need to be discussed by the _whole project team_. +** Something that we feel is extremely important to do +** There will only be _very rare_ exceptions, and these need to be discussed by the _whole project team_ * Consider -** Something that is our default approach, but we sometimes choose not to do when we understand the implications. -** These exceptions must be discussed in an _early review_. +** Something that is our default approach, but we sometimes choose not to do when we understand the implications +** These exceptions must be discussed in an _early review_ * Avoid -** Something that we try not to do, but may sometimes choose to when we understand the implications. -** These exceptions must be discussed in an _early review_. +** Something that we try not to do, but may sometimes choose to when we understand the implications. +** These exceptions must be discussed in an _early review_ * Don't -** 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_. - +** 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 @@ -84,7 +83,7 @@ h2. General * 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. +*** We only refactor code that we are actively working on, otherwise we live with the imperfections and tackle higher priority issues h2. Requirements @@ -98,8 +97,8 @@ h2. Design * DO ** Follow SOLID:http://en.wikipedia.org/wiki/SOLID_(object-oriented_design) design principles -** Prefer composition over inheritence. ** Use type inference (var in C#) to aid refactoring in the long-term. Less files touched = cleaner changesets. +** Prefer composition over inheritence * 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 @@ -134,7 +133,7 @@ h2. Documentation ** 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 * CONSIDER -** Adding an XML code comment for namespaces to describe their scope and responsibility. +** Adding an XML code comment for namespaces to describe their scope and responsibility * AVOID * DON'T @@ -153,7 +152,7 @@ h2. Testing h2. Build/Deploy * DO -** Keep the build green at all costs +** Keep the build green at all costs. *** Panic when the build goes red - establish who is working to resolve the issue *** Prioritise fixing the build over finishing a story ** Treat build/deploy scripts as first class citizens From 527314372468255287e24cb68b3188a8f3a2e38c Mon Sep 17 00:00:00 2001 From: Nathan Evans Date: Wed, 28 Nov 2012 14:50:29 +0000 Subject: [PATCH 07/14] Add more points to Testing section. --- README.textile | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/README.textile b/README.textile index 091f418..3daf577 100644 --- a/README.textile +++ b/README.textile @@ -141,9 +141,13 @@ h2. Documentation h2. Testing * DO -** Use unit tests as your primary test mechanism +** Use automated tests as your primary test mechanism +** Treat automated tests as first class citizens in the code base; refactor them, polish them +** Implement your tests for behaviours but not implementation details such as particular methods * CONSIDER -** Adding smoketests to validate components +** Adding smoke tests to validate components +** Writing your test cases before your implementation, where appropriate +** Validate your assumptions[8] by modifying either the implementation *or* the test, but never both together * AVOID ** Extensive usage of stubs and mocks in unit test setup * DON'T @@ -179,3 +183,4 @@ fn6. Immutable Types:http://msdn.microsoft.com/en-us/library/hh297115(v=vs.100). fn7. Pure Functions:http://blogs.msdn.com/b/ericwhite/archive/2006/10/03/pure-functions.aspx +fn8. Replacement C# compiler and TDD:http://skillsmatter.com/podcast/java-jee/itb-greg-young \ No newline at end of file From 445b29f20df0113e2a892632115c8ad07a02d6c6 Mon Sep 17 00:00:00 2001 From: Nathan Evans Date: Wed, 28 Nov 2012 14:52:29 +0000 Subject: [PATCH 08/14] Add new section on Revision Control. --- README.textile | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.textile b/README.textile index 3daf577..19d8c4c 100644 --- a/README.textile +++ b/README.textile @@ -167,6 +167,17 @@ h2. Build/Deploy * DON'T ** Disable any automated tests +h2. Revision Control +* DO +** Use "atomic" commits +** Collaborate with your team to help avoid (potentially) costly manual merges +* CONSIDER +** Wording your commit messages in future tense e.g. "Fix memory leak in AcmeController" not "Fixed bug..." +* AVOID +** +* DON'T +** + h1. References/Further Reading fn1. Simple Made Easy:http://www.infoq.com/presentations/Simple-Made-Easy-QCon-London-2012 From 8b1d139e2f8fb3564161c87c5294383c8f5437c8 Mon Sep 17 00:00:00 2001 From: Nathan Evans Date: Wed, 28 Nov 2012 14:53:09 +0000 Subject: [PATCH 09/14] Remove new line before Testing section. --- README.textile | 1 - 1 file changed, 1 deletion(-) diff --git a/README.textile b/README.textile index 19d8c4c..2a103f6 100644 --- a/README.textile +++ b/README.textile @@ -137,7 +137,6 @@ h2. Documentation * AVOID * DON'T - h2. Testing * DO From 68eb91858c04604e709b8e193f50094ac7d7af6b Mon Sep 17 00:00:00 2001 From: Nathan Evans Date: Wed, 28 Nov 2012 14:54:35 +0000 Subject: [PATCH 10/14] Remove point about type inference; too detailed and language-specific for this document. --- README.textile | 1 - 1 file changed, 1 deletion(-) diff --git a/README.textile b/README.textile index 2a103f6..ac2ee8f 100644 --- a/README.textile +++ b/README.textile @@ -97,7 +97,6 @@ h2. Design * DO ** Follow SOLID:http://en.wikipedia.org/wiki/SOLID_(object-oriented_design) design principles -** Use type inference (var in C#) to aid refactoring in the long-term. Less files touched = cleaner changesets. ** Prefer composition over inheritence * CONSIDER ** Pursuing a functional approach - immutable types, "pure functions":http://en.wikipedia.org/wiki/Pure_function etc From 94d2abe26b5316e1b044834fd92e2e8312dec2a7 Mon Sep 17 00:00:00 2001 From: Nathan Evans Date: Wed, 28 Nov 2012 15:17:38 +0000 Subject: [PATCH 11/14] Normalise all line endings on bullet points to end with a full stop. --- README.textile | 110 ++++++++++++++++++++++++------------------------- 1 file changed, 55 insertions(+), 55 deletions(-) diff --git a/README.textile b/README.textile index 66b6cea..54307d0 100644 --- a/README.textile +++ b/README.textile @@ -68,49 +68,49 @@ The guidelines have been further categorised (idea stolen from "Framework Design Guidelines"[8]) into: * Do -** Something that we feel is extremely important to do -** There will only be _very rare_ exceptions, and these need to be discussed by the _whole project team_ +** Something that we feel is extremely important to do. +** There will only be _very rare_ exceptions, and these need to be discussed by the _whole project team_. * Consider -** Something that is our default approach, but we sometimes choose not to do when we understand the implications -** These exceptions must be discussed in an _early review_ +** Something that is our default approach, but we sometimes choose not to do when we understand the implications. +** These exceptions must be discussed in an _early review_. * Avoid ** Something that we try not to do, but may sometimes choose to when we understand the implications. -** These exceptions must be discussed in an _early review_ +** These exceptions must be discussed in an _early review_. * Don't ** 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_ +** 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 +** Use simplicity as the primary metric when evaluating competing options. * CONSIDER -** Automating repetitive tasks +** Automating repetitive tasks. * AVOID -** Complex solutions -*** Only ignore this recommendation if the benefits are demonstrably overwhelming +** Complex solutions. +*** Only ignore this recommendation if the benefits are demonstrably overwhelming. * DON'T ** Repeat yourself! -** Fix it if it ain't broke +** 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. ** 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_ +** 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 +** Use simplicity as the primary metric when evaluating competing options. * CONSIDER -** Automating repetitive tasks +** Automating repetitive tasks. * AVOID -** Complex solutions -*** Only ignore this recommendation if the benefits are demonstrably overwhelming +** 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 +** 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. ** 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_. @@ -118,7 +118,7 @@ h2. General h2. Requirements * DO -** Ensure that acceptance criteria are clearly identified before starting work on a story +** Ensure that acceptance criteria are clearly identified before starting work on a story. * CONSIDER * AVOID * DON'T @@ -126,16 +126,16 @@ h2. Requirements h2. Design * DO -** Follow SOLID[9] design principles +** Follow SOLID[9] design principles. * CONSIDER -** Asking for a design review at any point of working on a story +** 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 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] +** 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 +** Constructing invalid 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 @@ -144,65 +144,65 @@ h2. Design h2. Review * DO -** Get a code review when you think you've finished implementation -** Guide reviews using SOLID[9] principles +** Get a code review when you think you've finished implementation. +** 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 +** 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[9] +** 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[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"[17] +** Write self explanatory code. +** Write readable unit tests. +** 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"[17]. * CONSIDER -** Adding an XML code comment for namespaces to describe their scope and responsibility +** Adding an XML code comment for namespaces to describe their scope and responsibility. * AVOID * DON'T h2. Testing * DO -** Use automated tests as your primary test mechanism -** Treat automated tests as first class citizens in the code base; refactor them, polish them -** Implement your tests for behaviours but not implementation details such as particular methods +** Use automated tests as your primary test mechanism. +** Treat automated tests as first class citizens in the code base; refactor them, polish them. +** Implement your tests for behaviours but not implementation details such as particular methods. * CONSIDER -** Adding smoke tests to validate components -** Writing your test cases before your implementation, where appropriate -** Validate your assumptions[18] by modifying either the implementation *or* the test, but never both together +** Adding smoke tests to validate components. +** Writing your test cases before your implementation, where appropriate. +** Validate your assumptions[18] by modifying either the implementation *or* the test, but never both together. * AVOID -** Extensive usage of stubs and mocks in unit test setup +** Extensive usage of stubs and mocks in unit test setup. * DON'T -** Test multiple scenarios in a single unit test +** Test multiple scenarios in a single unit test. h2. Build/Deploy * DO ** Keep the build green at all costs. -*** Panic when the build goes red - establish who is working to resolve the issue -*** Prioritise fixing the build over finishing a story -** Treat build/deploy scripts as first class citizens -*** The same rules and standards you apply to code apply to your scripts +*** Panic when the build goes red - establish who is working to resolve the issue. +*** Prioritise fixing the build over finishing a story. +** Treat build/deploy scripts as first class citizens. +*** The same rules and standards you apply to code apply to your scripts. * CONSIDER -** Backing out changes that break the build +** Backing out changes that break the build. * AVOID * DON'T -** Disable any automated tests +** Disable any automated tests. h2. Revision Control * DO -** Use "atomic" commits -** Collaborate with your team to help avoid (potentially) costly manual merges +** Use "atomic" commits. +** Collaborate with your team to help avoid (potentially) costly manual merges. * CONSIDER ** Wording your commit messages in future tense e.g. "Fix memory leak in AcmeController" not "Fixed bug..." * AVOID From b9116e9a9051952d0aa9557a1a24d430f6eee25b Mon Sep 17 00:00:00 2001 From: Nathan Evans Date: Wed, 28 Nov 2012 15:18:29 +0000 Subject: [PATCH 12/14] Remove warning about crying; seems a little out of place. --- README.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.textile b/README.textile index 54307d0..b94a570 100644 --- a/README.textile +++ b/README.textile @@ -139,7 +139,7 @@ h2. Design ** 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. +** Mix mutable state and lazy evaluation. h2. Review From 9263968a1bf6ebeba79f9b4ab429d90e55e0d398 Mon Sep 17 00:00:00 2001 From: Nathan Evans Date: Wed, 28 Nov 2012 15:18:57 +0000 Subject: [PATCH 13/14] Fix typo of the word "focusing". --- README.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.textile b/README.textile index b94a570..7922890 100644 --- a/README.textile +++ b/README.textile @@ -151,7 +151,7 @@ h2. Review *** 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. +** Focusing 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[9]. From c9539d176d7b8253618777d4696937c95812935d Mon Sep 17 00:00:00 2001 From: Nathan Evans Date: Wed, 28 Nov 2012 15:25:15 +0000 Subject: [PATCH 14/14] Added point about ubiquitous language to Requirements section. --- README.textile | 1 + 1 file changed, 1 insertion(+) diff --git a/README.textile b/README.textile index 7922890..aa9f963 100644 --- a/README.textile +++ b/README.textile @@ -119,6 +119,7 @@ h2. Requirements * DO ** Ensure that acceptance criteria are clearly identified before starting work on a story. +** Gather domain knowledge and terminology and use it to build a "ubiquitous language" that traverses developer, codebase, documentation and end customer. * CONSIDER * AVOID * DON'T