This repository has been archived by the owner on Aug 5, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 48
XML and PFW Coding Rules
Sebastien Guiriec edited this page Jun 26, 2017
·
1 revision
Following rules apply for Parameter-Framework configuration files only.
- All new sources must follow the coding style described hereafter.
- The existing sources will be converted either by scripting or manually, at the component owners' discretion.
Rules levels
- Mandatory: Must be applied with no exception
- Recommended: Shall be applied. If not, must be motivated with a comment.
- Optional: Is good practice to apply. Can be ignored if it harms readability for e.g.
| Mandatory | Files names are UpperCamelCase formatted. |
|---|---|
| Details | Exception: Structure files have a version suffix that is not UpperCamelCase formatted. |
| Do |
MySubsystem.xmlMyRules.pfw
|
| Don't |
mySubsystem.xmlmy_rules.pfw
|
| Comments | Exception: Structure files have a version suffix that is not UpperCamelCase formatted. |
| Mandatory | Files extensions are lower case formatted. |
|---|---|
| Details | Exception: Structure files have a version suffix that is not UpperCamelCase formatted. |
| Do |
MySubsystem.xmlMyRules.pfw
|
| Don't |
MySubsystem.PFWMyRules.XML
|
| Comments |
| Optional | Keep files short. |
|---|---|
| Details | Use xinclude whenever possible to structure the configuration. |
| Comments |
| Optional | Keep lines shorter than 100 columns. |
|---|---|
| Details | Mandatory whenever possible in structure xml files and '.pfw' files. Do not modify manually files generated by PFW. |
| Do |
<Component Name="my_component" Type="MyType"Mapping="Amend1:my_value,Amend2:my_value2,Amend3:0,Amend4:my_value3"/>
|
| Don't | <Component Name="my_component" Type="MyType" Mapping="Amend1:my_value,Amend2:my_value2,Amend3:0,Amend4:my_value3"/> |
| Comments |
| Mandatory | No trailing space allowed. |
|---|---|
| Comments |
| Mandatory | Indentation size is 4-columns. |
|---|---|
| Comments |
| Mandatory | Configuration files shall be indented. |
|---|---|
| Comments |
| Mandatory | Subsystem names are lower_snake_case formatted. |
|---|---|
| Comments |
| Mandatory | Subsystem names are lower_snake_case formatted. |
|---|---|
| Do | <Subsystem ... Name="my_super_codec"> |
| Comments |
| Mandatory | Component type names are UpperCamelCase formatted. |
|---|---|
| Do | <ComponentType Name="BestProcessorEver" ...> |
| Comments |
| Mandatory | Component names are lower_snake_case formatted. |
|---|---|
| Do | <Component Name="my_module_instance" ...> |
| Comments |
| Mandatory | Parameter names are lower_snake_case formatted. |
|---|---|
| Do |
<IntegerParameter Name="my_int_param" ...><FixedPointParameter Name="my_fixed_point_param" ...><EnumParameter Name="my_enum_param" ...>
|
| Comments |
| Mandatory | Value pair literals are UpperCamelCase formatted. |
|---|---|
| Details | Detailed description shall remain in the description attribute. |
| Do | <ValuePair Literal="OneSubframe" Numerical="0"/> |
| Don't | <ValuePair Literal="One sub-frame (sub-frame length is 20 ms)" Numerical="0"/> |
| Comments |
| Mandatory | Criteria names are UpperCamelCase formatted. |
|---|---|
| Do | <SelectionCriterionRule SelectionCriterion="MySuperCriterion" ...> |
| Comments |
| Mandatory | Description attribute shall not contain parameter range. |
|---|---|
| Details | This is the purpose of Min and Max attributes. |
| Comments |
| Mandatory | Description attribute shall not contain data format. |
|---|---|
| Details | This is the purpose of the parameter type. |
| Comments |
| Mandatory | Domain and domain group names are UpperCamelCase formatted. |
|---|---|
| Details | PFW domain group and domain name will be appended at XML generation time to form a configurable domain name. If domain group "MyGroup" contains the domain "MyDomain", it will become "MyGroup.MyDomain" configurable domain in generated XML file. |
| Do |
domainGroup: MyDomainGroupdomain: MyBeautifulDomain
|
| Comments |
| Mandatory | Configurable domain names are composed of UpperCamelCase formatted tokens separated by dots. |
|---|---|
| Details | This allows to informally group configurations into larger categories (domain groups) that can add meaning. |
| Do | <ConfigurableDomain Name="LargeCategory.CloserScopeCategory.CloseCategory" ...> |
| Comments |
| Mandatory | Configuration names are UpperCamelCase formatted. |
|---|---|
| Do | <Configuration Name="Default" ...> |
| Comments |
| Mandatory | Tabulation use is forbidden. |
|---|---|
| Comments |
| Mandatory | Subsystem structure file names are prefixed by "Subsystem". |
|---|---|
| Do | SubsystemLpe.xml |
| Comments |
| Mandatory | Single module structure file names are prefixed by "Module". |
|---|---|
| Details | Help to distinguish module and bundle structure files. |
| Do | ModuleMyAlgorithm_v3_2.xml |
| Comments |
| Mandatory | Multiple modules structure file names are prefixed by "Bundle". |
|---|---|
| Details | This allows to have more than 1 version of the same structure in 1 folder. Structure files including many single module files are also bundle files. |
| Do | BundleMyProcessing_v1_0.xml |
| Comments |
| Mandatory | Structure file names are suffixed with version info "_vX.Y". |
|---|---|
| Details | This allows to have more than 1 version of the same structure in 1 folder. |
| Do |
BundleMyProcessing_v1_0.xmlModuleMyAlgorithm_v3_2.xml
|
| Comments |
| Mandatory | Use tabulations for indentation (no other purpose). |
|---|---|
| Details | The PFW parser uses the indentation level to delimit blocks (as python), and supports only tabulations. |
| Comments |