IT:AD:Non-Functional Requirements:Technical Requirements

• [TFX:8r6gm] Define the availability of the application, in terms of % available for any 24-hour period.
• [TFX:8r6gn] Define the maximum amount of time a search will take, 95% of the time.
• [TFX:8r6go] Define the maximum amount of time a search will take, 99% of the time.

• [TFR:8r6gs:MUST] The application's code will be organized in layers and tiers according to Distributed Domain Design principles.

  • Rational: the DDD pattern promotes modularity and enhancability.

• [TFR:8r6gp:MUST] Development will be completed according to the SOLID Pattern. Especially:
  • the concept of backing every service with an interface,
  • using Dependency Inversion,
  • and Dependency Injection to hold things together, and
  • assembling lots of small classes doing one thing only.
  • the use of Tests
• [TFR:8r6gq] Prefer Acceptance Driven Design Tests: ADD is an evolution of Test Driven Development, focusing on automated tests of use cases inputs and outcomes, rather than the underlying code (see Automated Unit Testing). It focuses less on the development process used to create the application, and more on testing the end use of the application. See Behaviour Test Driven.
• [TFR:8r6gr] If you are going to still create Code unit tests, I know how hard TDD is to do. Really. But do it anyway. One way to not freak out by that statement is to understand that tests do not need to be fine grain – just general at first (“Save Invoice”), adding detail later (+“Save Invoice with Validation of whatever”).

• [] Teams assemble and dissemble over time. Code clarity makes the code very easy (read: fast/cheap) for the next person to understand what you were doing.
• Use local variables freely, so that breakpoint can be set to inspect return values, etc (read: let others inspect/learn what you were doing). C# Uses brackets on the next line. JS uses brackets on the end of the first line. Private vars are lowercase and start with “_” Protected and Public vars are Camecase. Constants for Cache keys etc are made public in their own nested Constants class. One class per file. Make it easier to navigate/find them at a glance. #### Avoid Avoidable Bugs ####

Bugs = Development Cost.

Stupid bugs = avoidable cost.

Use brackets even for one line if/else statements. Saves on bugs (read:dev cost) Avoid Avoidable Poor Performance

Avoid IEnumerable if you don't understand it has on ORM objects (hits the db multiple times) Add tracing everywhere. Defer the cost of string.format by passing the variables to the ITracingService, rather than string.Formatting first before passing it to ITracingService. Comments

Commentless code – and those who ask for it – is a fools game. I'm not interested in how good you are. I'm interested in how cheap it is to maintain the code using a varying team of developers. So don't bug me about “how comments detract from the cleanliness of pure code” ever again. Ever. The amounts of times I've heard it mentioned to me over the years…argh! The number of times I bothered team leads about the exact same thing when I was an intermediate know-it-all…argh! (Embarrassing). Within methods: Do it for clarity. 6 months later code – even for the person who wrote it – is hard to groke as easily as english. Use english to say what it was doing (read: cheap to get up to spead). Regarding using wise cracks and swear words in your comments: no problem with personal comments. Unless the code will be shared with the client. Use common sense. Err on being safe.

Method Documentation: Automated documentation with tools such as GhsotDoc is doesn't add value directly. What I mean by that is that if the method name and argument names are clear, one can understand the functionality from the name. But…GhostDoc fails to work correctly unless a well chosen name is used in the first place. So indirectly, it teaches developers to use very very clear names for their methods and arguments (so does Resharper btw). And therefore – indirectly – the code understandability is improved. It's just a tool to enforce a better convention.

Embedded Documentation: With http://yuml.me, http://websequencediagrams.com and other text based/DSL diagramming tools, a lot of information can be embedded into a solution file without having to resort to an external unrelated sharepoint site (shudder). Plus it's change-controlled.

Per Project: create a '_Readme' folder (the underscore gets it high and out of the way) in each *.csproj and add about.txt, etc.

Per Solution: Use explorer to create a _Documentation folder in the .sln root folder. Note that Visual Studio has a 'feature' that doesn't help (When Adding New document at the solution level, it creates them in the solution root…messy). Instead, use Explorer to create your .txt files, and then use visual studio to Add Existing…cleaner file structure).

CheckIn Comments: Checkin comments are underused as they are only looked at from the developer's point of view during development– not project metrics, nor subsequent support. They're mandatory. Checkin code with prefix of Project/Client:Solution:State(Build|Runs|Broken):Comment Humour/wisecracks as to code quality, etc. is fine – unless the code history stands the chance of being shared with the client at the end of project.