OGRE Coding Standards 编程规范
2012-07-27 21:14
375 查看
OGRE Coding Standards
This document describes the coding standards all developers are expected to adhere to when writing code for the OGRE project.Top-level organisation issues
All source files must begin with the standard OGRE copyright statement:/*------------------------------------------------------------------------- This source file is a part of OGRE (Object-oriented Graphics Rendering Engine) For the latest info, see http://www.ogre3d.org/ Copyright (c) 2000-2011 Torus Knot Software Ltd Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE -------------------------------------------------------------------------*/
All publicly visible classes should be declared in their own header file using the .h extension, placed in the 'include' folder of the sub-project in question, and named after the class but prefixed with 'Ogre' e.g. 'OgreMyClass.h'. Only very tightly related
classes should be declared in the same header file.
Implementations should be placed in a source file called the same name as the class but with an extension of .cpp.
Everything must be declared inside the namespace 'Ogre'.
Portablity
All code must be cross platform, ANSI C++. No dependencies on platform-specific headers and / or types are allowed (the only exception is when dealing with platform-specific features like windowing, which must be implemented for each platform separately).If you serialise / deserialise any data, subclass from Serializer and use its methods, it will insulate you from endianness issues. If you need to serialise any types it doesn't already handle, make sure you deal with endianness issues in the same way Serializer
does (ie use native endianness by default but detect the inverse on reading and perform flipping if required).
C++ Standards compliance
Always prefer the STL over custom containers / algorithms.Always prefer C++ techniques over C.
Avoid C-strings (char* and functions like sprintf, strcpy, use Ogre::String)
Avoid old I/O routines (fopen et al, use <iostream>)
Use abstract classes or templates not void*
Use overloaded methods not varargs.
Minimum C++ compiler level is MSVC 7.1 or gcc 3.1. Compilers which do not support things like partial template specialisation properly (such as older versions of MSVC) are not supported.
Use the PImpl idiom to reduce dependencies between classes.
Always use
const-correctness. Methods taking non-primitive types as parameters should generally take them as const references, methods returning non-primitive types should generally return them as const references. Declare all methods
that do not modify internal state 'const'. For lazy-update getter methods, declare the internal state which is lazy-updated 'mutable'.
Prefer 'protected' over 'private' to encourage specialisation where appropriate
Always declare destructors 'virtual' unless the class you are writing should not have any vtable (no other virtual methods).
Avoid non-const by-ref parameters unless you have no other option. We prefer not to have in/our parameters since they are less intuitive.
Naming conventions & Documentation
Classes, types and structures must be title case (MyNewClass).Methods and local variables must be camel case (myNewMethod).
Member variables should be prefixed with 'm' (mInstanceVar), static member variables should be prefixed 'ms' (msStaticMemberVar). Do not use any other prefixing such as Hungarian notation.
Preprocessor macros must be all upper case and prefixed with OGRE_
Enums should be named in title case, enum values should be all upper case
All classes and methods must be fully documented in English using Doxygen-compatible comments. Use the @param and @returns directives to define inputs and outputs clearly, and @note to indicate points of interest.
Use verbose, descriptive names for classes, methods, variables - everything except trival counters. Code should be self-describing, don't be obtuse.
Memory Management
Full virtual classes should derive from an AllocatedObject template instantiation typedef'ed in OgreMemoryAllocatorConfig.h. This will define custom new/delete operators on the class. Small, non-virtual value classes like Vector3 should not.Never use new/delete directly.
For classes derived from AllocatedObject, use OGRE_NEW / OGRE_DELETE as drop-in replacements for new/delete
For other classes which need a constructor / destructor, use OGRE_NEW_T and OGRE_DELETE_T. If you know there is no destructor, you may use OGRE_NEW_T and free with OGRE_FREE for speed
For primitive types, use OGRE_ALLOC_T and OGRE_FREE
Be aware of allocator issues when using SharedPtr
Classes derived from AllocatedObject can just be constructed using OGRE_NEW and wrapped, no special behaviour
Classes constructed using OGRE_NEW_T must be allocated using MEMCATEGORY_GENERAL, and you must set the SharedPtrFreeMethod parameter to SPFM_DELETE_T
Instances constructed using OGRE_ALLOC_T must be allocated using MEMCATEGORY_GENERAL, and you must set the SharedPtrFreeMethod parameter to SPFM_FREE
When defining STL containers, instead of using std::vector or std::list etc, use the memory-manager enabled versions vector::type and list::type respectively (most containers have this equivalent). This defaults the memory manager to the General type, but
you can override the last parameter to the template if you want an alternate type.
Style issues
Insert a newline before an open brace (contentious I know!)Use typedefs to declare template-based types that you use to avoid ugliness e.g. typedef std::list<MyType*> MyTypeList;
Always insert spaces in between operators and operands (x + y, not x+y)
Use parenthesis to make the operator precedence unambiguous, even when it is not required ((x * y) + 1, not x * y + 1)
Error handling
Fatal errors should always be dealt with though exception handling. No return-value error reporting.Whenever you make an assumption in your code, verify it with an assert().
Design issues
Use existing design patterns and identify them by their well known names. A good starting reference is the 'Gang of Four' book.Use strong encapsulation. Top-level interfaces should hide implementations and not require the user of the library to understand internals. Avoid public attributes except in structs.
Don't use 'friend' if you can avoid it. Where classes need to collaborate on an internal implementation, prefix the methods they use to communicate with '_' (this is our demarcation for 'recommended for internal use only'). This can also be used to expose
advanced functionality only intended for very skilled users.
Final words
If in doubt, do as the existing code does!相关文章推荐
- OGRE 编程规范 OGRE Coding Standards
- JAVA 编程规范 Coding Rule
- C# 编程规范 (coding standard)
- 架构师任务--制定代码规范(Standard of Coding Standards)
- 1、Linux编程规范-C Coding Standard
- 架构师任务--制定代码规范(Standard of Coding Standards) [转]
- .Net 编码规范(CSharp Coding Standards)
- 架构师任务--制定代码规范(standard of Coding Standards)
- CERT Secure Coding Standard — C语言安全编程规范
- 华为软件编程规范和范例
- 简明 Python 编程规范
- 华为软件编程规范和范例
- Android_编程规范
- C# 编码规范和编程好习惯
- JavaScript编程规范-有利于效率和可读性
- Java8 编程规范入门之【forEach方法遍历集合】
- 简明 Python 编程规范v2
- Google C++ 编程规范——背景
- 编程之规范(四)