Library/Software Engineering/Elements of a Good Component
From Athile
- Documentation
- Conceptual Overview (if this is long or complicated, its a warning sign of a poor design!)
- API documentation (should be concise and self-explanatory)
- Tutorials
- Unit tests (test for regressions)
- Demos (show what the features can provide for the user)
- Samples (show developers how to use the features)
Contents |
Design Principles
Keep it simple
Keep it simple: LxEngine is designed to be an easy to learn, use, and extend. These are the priorities; they are above producing an engine with optimal performance at the expense of code maintainability.
For example, if plug-ins can be written via dynamically loaded Javascript files without noticeable performance penalties or coding complexities, then do so. It will keep the system more modular and easily modified.
Use standards
Use standards: as part of making an easy to learn engine, use standards. If a std::map<> can be used to store a data set, use a std::map<> since many developers are already familiar with that class. If std::map<> won't work and a custom class must be written, make it behave as close to std::map<> as possible and call out the places where they do not behave the same.
Design for the user, not the implementation
Design APIs for the user, not the implementer: design core APIs how would be most straightforward, convenient, and symmetric for the user of those APIs. Approach this from a 'clean room' perspective, ignoring how they would need to be implemented.
This project has no deadlines, no investors, not pressure: design for the right design.
Encapsulate rather than reimplement
LxEngine is intended to be a full engine: meaning sound, graphics, physics, i/o, etc. LxEngine should act as a hub, or a Facade, that provides consistent APIs and behaviors from each of these subcomponents. However, it should leverage third-party open source SDKs to provide the implementation of those subsystems. This means LxEngine has the advantage of providing a consistent interface to the programmer for all subsystems, but also automatically benefits from the open source community's work.
Warn about (but don't fix) common API usage errors
LxEngine, unlike an engine focused entirely on performance, should try to identify common mistakes in API usage, etc. For example, if a mesh "Ref" element has it's "position" attribute set and the correct way to set position is via the "translation" attribute, then the engine should warn the user about this but not accept position as an alias.
Again, the code should look for common errors when it makes sense to do so, but it should not try to correct them for the user.
This will keep the code self-instructive but also still allow a strict, formal, well-defined API.
