Home

Welcome to the Ara3D Development Wiki

Guiding Principles

• The most important role of code is designed to be read, understood, and reused by other programmers
• Follow the SOLID principle (https://en.wikipedia.org/wiki/SOLID)
• Mutable state (particularly shared) is the root of all evil
• Don't Repeat Yourself (DRY)
• Code is technical debt
• Refactor as you go
• Good modular programming should be considered at all levels: assemblies, classes, interface, and functions
• Minimize dependencies/coupling
• Abstractions should have a single clearly defined role
• Start with the simplest thing that could possibly work
• Don't make others think when they read your code
• Tests should be useful
• Code should be maximally useful in other contexts

C# Coding Style

We follow largely the Microsoft .NET coding guidelines with some customizations.

First rule is: know the code base and reuse it, follow its style, and refactor it.

Various guidelines:

• Prefer Var over explicitly typed variable declarations
• If a function can be broken up into small static functions that could be reused then do it
• Static functions must be marked as static
• When adding documentation for a function or class, only use a summary (delete auto-generated parameter, return, and type-parameter entries)
• Prefer to make data public
• Structs must be immutable
• Classes are much preferred to be immutable
• Prefer fluent syntax where it makes sense (makes auto-complete nicer)
• Try to avoid hard-code paths
• Prefer Expression-body syntax for properties and functions
• Don't use internal
• Don't be afraid of one letter variable names, where it makes sense and improves readability
• Maximum one line of continuous white-space
• When a function is longer, try to group the statement into logical groups with single line comments
• Avoid useless or self-explanatory functions
• If a function does two independent things, then it is a candidate for being refactored into a function that calls two separate functions
• Aim to remove as much as possible state shared between functions
• Virtual functions should be avoided as much as possible
• Prefer interfaces
• As much as possible code should exist on interface extension functions, so that it as reusable as possible
• Functions should be liberal in what they accept
• Pass by out/ref parameters should be avoided
• Use descriptive and accurate names for variables