General Design Principles
- Simplicity, Simplicity, Simplicity
- Components / Utility code that is generic and can be used across different companies
- Easy to use API's as a result of Test Driven Development & real-world needs / use-cases
- 0 xml config files ( You should not require any xml config file to be required to configure any components ). Programmatic / Fluent validation only.
- 0 third-party / external dependences ( This project does not use any other dlls other than Nunit for unit-tests )
- Concise names
- Good documentation and examples of all components
Listed below are the coding conventions that should be generally followed. There may be instances where 1 or more of these conventions may not apply.
Every single coding convention ( e.g. naming conventions for members / classes) has not been listed because for the most part they are in line w/ code conventions in most other projects such as Enterprise Library, Spring Core, and conventions listed by microsoft
itself. However the conventions listed below are particularly important within commonlibrary.
- Methods should not bee too long ( Ideally a method should fit on a computer screen
- Classes should not be too long ( Perhaps no more than 1000 lines of code per class ? )
- Avoid methods with more than 7 parameters
- Avoid over-engineering
- Avoid long names for variables, parameters, classes, methods etc.
- Private / protected data members must be prefixed with '_' as in private int _userId;
- 2 lines of space between methods
- 3 lines of space between classes
- Classes should have the following sequence of code in sequential order:
- Static code : public properties, methods
- Instance code: public constructors, properties, methods
- Instance code: protected properties, methods
- Instance code: private properties, methods
- Avoid cyclic references within the projects ( Can be detected using NDepend ) - currently being cleaned up.
- Document all public / protected methods
Process for bug fixes
- Make bug fix
- Add / update unit test for the bug-fix ( Unit Tests are located in the "Unit Tests project"
- Run all unit-tests unit NUnit. ( Make sure to run all the unit-tests not just the unit-tests for your project, this is because there may be a possiblity that the component you changed/fixed is being used in another component )
- If tests pass, check-in code to repository(SVN)
- New components should be in their own namespace
- New components should be in their own folder
- A typical set of classes that tend to be included in a component are "Component", "ComponentService", "ComponentConstants", "ComponentHelper", "ComponentValidater" etc.
- New components should have unit-tests
- New components should have an example app ( See below )
- Each file that is added or part of a new component must contain the "License" text at the top of the file ( See any file as an example )
- Each component's namespace must begin w/ "ComLib"
- Example code is located in <ROOT>\src\Lib\CommonLibrary.NET\Samples for various components
- Examples are compiled as part of CommonLibrary.NET to make sure the examples are valid w/ respect to any updates
- Example code for a new component be named with convention being Example_<ComponentName> e.g. Example_Arguments
- Every example should be tested after being written the first time and after any changes to the component that its associated with.
- Every example implements the IApp interface