SAP Hybris Best Practices Guidelines

SAP recommends following guidelines for Hybris developers.

1. Define a deployment table for all Item Types extending GenericItem. All types that explicitly or implicitly (because it is the default) have GenericItem as their direct super type should have their own deployment. The only exception to this rule is an abstract item type.
2. Do not define a deployment table for any Item Types that already have a deployment inherited from a super type. This is because it can cause serious performance issues because queries for the super type require a UNION clause with the new table.
3. Deployment type codes must be greater than 10000. Type codes in deployment clauses up to 10000 are reserved for types defined within the SAP Commerce product. Developers defining new item types for inclusion in the product must select a type code larger than 10000 and register that in the file, reservedTypecodes TXT file (Found at platform/ext/core/unittest/reservedTypecodes.txt). Once released as part of the product, entries must not be removed from the reservedTypecodes TXT file.
4. Do not define a Jalo class if existing item types are being modified.
5. Define a deployment table for all many-to-many relations. If a many-to-many relation does not define a deployment table, its data will be stored in the links table along with the data from all the other many-to-many relations that do not define a deployment table. This can cause that table to have a very large number of rows, large indexes and this will cause performance issue.
6. Ensure mandatory fields (where optional=’false’) have either initial set to true or a default value defined.
7. Ensure immutable fields (where write=’false’) have initial set to true. Setting write=”false” means that a value can only be set when an Item is first created. Setting initial=”true” effectively achieves the same. For consistency you should set initial=”true” when write=”false”.
8. Define Boolean attributes as mandatory.
9. Start Item type Names (including EnumTypes and Relations) with an uppercase letter.
10. Do not start Item type names with Generated.
11. Start item type attribute names with a lowercase letter.
12. Start qualifier names in relations with a lowercase letter.
13. Avoid setting ordered=’true’ on any side of a relation that has cardinality=’many’ unless absolutely necessary. Order=”true” has a significant impact on performance when reading and writing from the database. The queries required to provide a defined order to the items that are returned are much more complex and expensive that an unordered query. 
14. Use collectiontype=’set’ on any side of a relation that has cardinality=’many’ where items must not appear in that relation multiple times. The set guarantees that every relation is persisted only once.
15. Mark CatalogVersion attributes as unique for Catalog aware types. The CatalogVersion attribute forms part of the unique key for Catalog Synchronization. To ensure that the same uniqueness rules are applied for other processes (for example, ImpEx), you need to set the CatalogVersion attribute to unique=”true”.
16. Ensure unique attributes match the catalog unique attribute key, uniqueKeyAttributeQualifier. The attributes defined as unique for the type should be the same attributes as those defined in the custom property, uniqueKeyAttributeQualifier. The uniqueKeyAttributeQualifier custom property defines the unique attributes for Catalog Synchronization whereas processes using the Service Layer (including the Catalog Sychronization persistence) use the unique attributes on the type.
    
17. Define database indexes for the unique attributes of type. There should be a covering index defined that includes all the unique attributes for type. There are Service Layer interceptors that validate uniqueness for each type, which generate a query for all the unique attributes. Failure to add an index can cause serious performance issues. Furthermore, the validation of the unique attributes in the Service Layer cannot guarantee that there won’t be duplicate records in the database, only a unique index/constraint can do this.
18. Ensure catalog aware types are not part of a one-to-many relation when the many side is not a catalog aware type. Creating a one-to-many relation where the one side of the relation is a Catalog aware type and the many side is not a Catalog aware type causes an issue when synchronizing. The reference to the Catalog aware type will be transferred from the Staged to the Online version. The Staged version will not longer have a reference. 
19. Ensure all types have unique attributes. Every type should have a unique identifier(s) defined or should inherit the unique attributes from a super type. This allows the data to be easily imported or exported into different systems and prevents duplicate entries in the database.
20. Choose whether to add to an existing item type or create a new sub-type carefully.
21. Describe the purpose and intended use of an attribute in a description tag.
22. Remove unnecessary indexes. Index management is cost intensive. As a rule of thumb, indexes should only be added for attributes used in flexible searches.
23. Localize any attributes that need to be displayed in a different language.
24. Avoid using collections and use relations instead.
25. In general, the use of relations is preferable to the use of collection types. Collection types can be subject to truncation issues so unless you have very good reasons to use one, use a relation instead.
26. Define types in order of inheritance. More abstract types need to be defined more to the beginning of the items.xml file and more concrete types need to be defined more to the end.
27. Type names must be unique. Before defining any new item type, make sure that there is no type with the same name in any other extension. The build system will complain if you try to create two types with the same name, and implementors will not be able to use both extensions in the same project.
28. Do not change attribute definitions unless absolutely necessary. The modification of an attribute qualifier has serious consequences on a system update. A change of upper/lower case spelling will cause API incompatibilities because the signature of generated getters/setters will change. A change of spelling is same as removing the attribute from items.xml and defining a new one with different name. With that the data will be stored in a new column, the old data is not accessible anymore by generated API. There is no automated way to fix this problem.
29. Do not change deployment code or table names unless absolutely necessary. The typecode specified in a deployment tag forms part of the PK of the items inside the database. It helps find items very quickly by their PK because the typecode points directly to the correct database table. When a typecode is changed for a table, all old items inside the table will not be found anymore and are lost with it. If table name is changed, you get a new table, and you lose access to the old data .
30. Do not change a type declaration unless absolutely necessary.
31. Define a database index on the lookup value of reference types.

Note: For detailed information, please visit SAP CX page.