Professionalism, Craftsmanship, Discipline
These notes are really for my own use. A handy place to remind myself of how I should code. They’re very much a work in progress and I’ll refine and add to them as quickly as I can. I’ll continue to curate them for as long as I’m coding.
These are my notes on the standards I apply when writing my own code for my own projects. When writing code for others I would expect, like any other team member, to have an input into coding standards discussions, but of course, I follow the team guidance.
I write most of my code in C# and these notes are focussed on that language. I do occasionally write Java & more than occasionally JavaScript, where I sensibly apply the same principles. I have noted some differences where it feels appropriate.
It’s all about the Team
Software development is mostly a team sport. Standards need to be agreed within the team. Everyone in the team should use the same standards and the care with which we apply them means the code itself documents our standards.
Knowing
Writing code means making decisions all the time, from where to leave a break between lines to how to structure an application. It’s natural as you become more experienced to make many decisions on auto pilot, especially the small ones.
Some decisions will be better than others and, do doubt, some will be regretted later.
The key is to know that you understand why you made each decision, even a small one. By ‘know’ I mean that you can clearly articulate your reasons, even if only to yourself.
It’s that understanding that feeds the continuous improvement that leads to more good decisions and less bad ones.
SOLID Principles
No professional C# developer, or developer in any OOP language can be unaware of the SOLID principles which underpin modern maintainable code. Because I like to remind myself of them frequently I put them on my website here.
Test Driven Development
I develop my code using TDD, which has three phases…
- Red: Write a failing test.
- Blue: Write just the code needed to pass the test.
- Green: Refactor to make the code and test suite meet the coding standards.
During the Blue phase I don’t pay too much attention to code smells. The purpose of the Green phase is to refactor these out.
My target is for a typical Red-Blue-Green cycle to be as short as possible; from 30 seconds or so to a few minutes. I don’t commit code in the Blue phase.
I sometimes refer to these phases in notes below.
Good use of TTD shortens debug time, provides low level documentation of your code and removes the fear of refactoring.
I’ve met many TDD sceptics. For simple use cases I can produce bad code quicker without TTD. In more complex situations and where good code is important (always, surely) then TDD is the quickest way to deliver a working, maintainable product and lowers the the cost not just over time but the cost to initial delivery.
Code Coverage
My target is always 100% code coverage. It’s not always possible so for green field projects I set a minimum acceptable level, which is usually above the 90% mark.
For legacy goal I always set myself the target of increasing code coverage every time I touch the code.
I typically exclude generated code from my test coverage and, of course the tests themselves. Everything else is included.
Microsoft Guidance for C#
Since C# is my primary weapon here’s a link to Microsoft’s C# Coding Guidance
Coding Notes
Naming Classes & Types, Methods, Parameters, Fields etc
Adding Comments to Source Code
Almost none of these notes rely on discoveries I have personally made but rather are a distillation of what I have learned from others, all of whom have my sincere gratitude.