.NET技术-.NET理论资料-Amoskeag coding rules

Amoskeag coding rules

For the code created for BSD Amoskeag project, the rules below supersede HSL coding guidelines.  Note that these are not guidelines, but HARD RULES.  No code will be accepted if not complying with these rules.  Some of the rules contain recommendations; only those are not required.

Note that the existing code does not comply with the rules 100%, although it mostly does.  Since we request 100% compliance from our developers I suggest that QC engineers check every submission for full rule compliance and collect their statistics from submissions only.


Main rule:

1. Follow existing code structure and conventions as much as possible.  We have to maintain existing development style to have our code accepted.

File rules:

1. When adding new files: maintain project structure (determine appropriate project and project folder); maintain folder structure; start file name with "Aecb" prefix, continue with "Ui", "UiCmd", "UiDlg" as appropriate, then follow with object/function name.  For database object and their implementations continue with "Col", "DbCol" or "ImpCol" as appropriate, then object name.  Extension should be ".cpp".
   
2. Header files should have the same names as source files, extension replaced with ".h". Header files have their own structure: headers local to project go to the project's own "Inc" folder; inter-project headers go to "Source\Inc" or "Source\Inci" folders - as determined by Autodesk reviewer.
3. Deleting or moving of existing files is not allowed unless authorized by Autodesk reviewer.
4. Every source or header file should have the standard Autodesk header.  See existing code.
   

Resource rules:

1. Resources and export definitions should be added to the appropriate existing files.
2. All strings visible to users have to be entered as resources.  Strings that are not visible to users but required for certain API have to use _DNT macro.
3. Use AecRmCString and AecRmCStringArray classes for resource strings; use appropriate macros to convert to AecRmCString. No MFC string classes allowed.
4. When passing strings as function parameters, use const-reference for input and or reference for output strings.
5. Messages can be displayed with AfxMessageBox or Ac print function. Prompts should use appropriate Aec utilities with monitors.
   

User interface rules:

1. Use MFC for all UI tasks, use MFC types when appropriate except strings.
2. Allocate twice as much space as required for English strings for static strings in dialogs.
3. Try to match existing dialogs in terms of fonts and layouts.
   
4. Dialogs should be based on Aec UIDlg base classes.
   

Naming rules:

1. Class names obey the same convention as file names.  No additional prefixes or suffixes. Class name should be the same as file name.
2. Hungarian variable naming convention is strictly enforced, including using "m_" for member variable names.  The convention is extended to use some Aecb-specific object prefixes, such as "id" for object ids or "cs" for strings.  Again, follow existing code as much as possible.
3. Class and type names should start from capital letters; function names start from small letters. No underscores should be used in any names (except for member variable prefix); new words in names start with capital letters.

Coding rules:

1. Multiple class definitions in the same file are not allowed, except nested (classes within classes or functions) classes.
2. Global functions or variables are not allowed, except when required by APIs.
3. Use AEC_ASSERT macro to check developer error conditions, such as function parameters and important intermediate check-points.  Try to fail graciously (prevent crashes) in case of an assertion. Standard assertions or console print-outs should not be used.
4. Use try-catch clauses only for specific exceptions that represent expected failures.  Never catch all exceptions: catch(...).
5. Check returned error codes from the utility functions and add appropriate logic to handle error conditions.
   
6. All local variables have to be initialized when defined, all member variables have to be initialized in the appropriate constructors.  Exception: variables with appropriate default constructors.  Limited scope variables are encouraged.
7. Use MFC or STL for algorithmic utilities (vectors, maps), but try to minimize type conversions.  Use Aec/Aecb algorithmic utilities when possible.
   
8. Use enumerations for all logical state flags as appropriate.  Do not hard-code numbers when coding logical statements.
9. Use const statements as appropriate for accessors or non-modifying functions in data classes.  Use const references / pointers for object-type parameters not modified by functions.
10. Do not use any technologies that are not used by the existing code; we cannot introduce new dependencies unless specially permitted.

Code layout rules:

1. Indent code with tab of size 4 (set tab and indent size as 4 and use "keep tabs" option).
2. { and } symbols and return statements must appear on their own lines.
3. Use empty lines to denote logical code blocks.
   

Commenting rules:

1. Fixed format comments are required for every function in source files and every class in header files.  See existing code.  No standard comments required for functions in header files, but section comments encouraged.  Member variables should have comments on the same line after their definition.
2. Source code comments are very important and should follow standard commenting rules.

Submission rules:

1. Every code submission must represent a reasonably completed feature or a defect fix.  Review your changes carefully before submission.  Make sure words are spelled correctly.  Cosmetic changes or changes not related to the implemented feature or defect fix will not be accepted.
   
2. Every submission must be accompanied by the description created with Subdoc tool.  See tool documentation and project specific instructions about the submission information to enter.
   
3. All compiler warnings have to be resolved before submission.