Coding Guidelines

Software Systems can easily pile up technical debt (see my Clean Architecture for more thoughts on that). One of the reasons is that people rush. Another common one is not thinking about or knowing about good software practices.

How do we teach this and rely the concepts? I don’t think a style guide and coding standards is enough, but I offer some principles to follow and share.

"Haste makes waste"

Principles to Follow

• SOLID Principles
  • “Easy to Change” - Pragmatic Programmer, edition 2
  • DRY - Don’t repeat yourself - don’t duplicated knowledge in the code - Pragmatic Programmer, edition 2
  • SOLID
  • These aren’t always easy to understand, but important principles to think about
• Follow the Boy Scout rule, Make code better than what you found it
  • Removed unused usings (in Visual Studio ctrl + k, ctrl + e will format, remove unused usings and sort them)
  • Removed unused parameters and variables
  • Delete unused code
• if you need to get something done fast, do your best, make is work, then plan to come back and clean up later (or the next time you touch the code). It’s a tradeoff (now or later).
• Use Dependency Injection
  • Inject Interfaces not classes
• Onion/Clean Architecture ideas
  • Use Interfaces
  • Abstract Details and put on the outer rim
    • Network, database, API and disk calls
  • Put business logic in the center/core
• Prefer Composition Over Inheritance
  • https://betterprogramming.pub/prefer-composition-over-inheritance-1602d5149ea1?gi=cde8270839e8
  • https://softwareengineering.stackexchange.com/questions/134097/why-should-i-prefer-composition-over-inheritance
• Strive for simplicity
• The best code is many times the code you don’t write, think through possible solutions before coding
• Try to make clean as consistent and readable as possible
• Try to make code understandable and straight forward
  • Use good variable names
  • Use good method and class names
• Add code comments when a decision was made, not to say what the code is doing
• Do you understand the business needs and how this work will create value for our clients or improve the system?
  • Remember your job as an engineer is create value
  • Many times there are solutions that don’t require adding more code
• Think and plan before writing code

Coding Suggestions

• Delete instead of comment out unneeded code
• Use Visual Studio’s /your IDEs code formatting before checking in (ctrl + k, ctrl + d)
  • Clean up empty lines, only have one before // one after }
• Reduce duplication (unless that same code is being used for different reasons)
  • https://channel9.msdn.com/Series/Visual-Studio-2012-Premium-and-Ultimate-Overview/Visual-Studio-Ultimate-2012-Finding-and-managing-cloned-code
• Group functionality in folders - NGW
  • Ex: OcFlow\CompleteOrder\Prepaid
• Create small specific classes
  • Avoid naming it * Helper as this suggests just adding more methods to this class
  • Strive for less than 250 lines
  • Keep the injected dependencies to less than 5 if possible, if there are more break it into smaller classes
• Refactor large Helper classes into smaller classes
• Put business logic in separate classes in the Core/center of the application
  • Re-usable, unit testable, doesn’t connect to outside data sources, should stay mostly the same over time
  • Put as much logic and orchestration in API, not in the UI layer
• Break large methods into smaller methods
• Avoid adding if blocks to fix code
• Add unit tests
  • Try to add tests before changing code to prove the bug (you may need integration tests)
    • This will give confidence that your changes are fixing the right things and not breaking others
  • Recognize the need for integration tests
• UI code - enable and communicate about UI automation if we are moving UI elements, we should add ids to the DOM and notify QA. These will make it easier. Add an attribute of auto-id=“xyz” for unique elements if there isn’t already an id=“xyz”. If there are multiple (like a list or tree), then we can add a class=“auto-xyz” to help. this approach was very helpful in the past
• Avoid regions
• Avoid nullable params and values
• Add guard checks for unexpected values (throw an exception)
  • Fail fast, throw custom exceptions for unexpected situations to avoid it failing later
  • Add information to help troubleshoot the problem
• Prefer specific new Exceptions over the generic Exception
• Upgrade Nuget/npm/etc packages when you add new code

Tools

• .editorconfig
• Roslyn Analyzers
• build time analyzers SonarQube/NDepend
• DevSecOps - scan for vulnerabilities in your code and the libraries you are using

Books and resources

• Clean Architecture - Bob Martin
• Working with Legacy Code - Michael Feathers
• Martin Fowler also has a Refactoring book
• Weekly Dev Tips
• Pragmatic Programmer
• many, many more

Approaches

Teaching takes time and effort. We all need to learn humbly from each other.

I think that Pull requests are an easy first step. Pair programming and working together is another good way. We need to hold each other accountable to create better code (or delete bad code) that’s readable, maintainable and sustainable.

I also suggest lunch and learns and book groups.

Keep learning and improving.

Feedback

There is much more that should be added and I’m sure I’ll come back and add more in the future as I think of more. I’m sure you have ideas, please let me know in the comments.