YANG Tools: Design and Coding Guidelines

YANG Tools:Design and Coding Guidelines

Contents

 [hide] 

• 1 Class and Interface Names
• 2 Getters and Setters
• 3 Best Practice
• 4 Source Code Structure and Build
  • 4.1 Package Names

Class and Interface Names

• Do not use "I" prefix for interface names. Use just plain, simple and relatively short names for interfaces. The user of the interface should not care whether he is using abstract class or interface (he should not create it using constructors anyway). Therefore use User, not IUser.
• It is not required to use able suffix for interfaces, but it helps in some cases. User is a perfectly good name for an interface as Userable, Userish or Userlike are quite queer. However, Readable is preferred to Read, Reading or other strange forms.
• Class names that implement interfaces should somehow be related to the interface that they implement (or the most important interface in case of implementing multiple interfaces). For example class implementing interface User could be UserImpl, UserMock, UserDbImpl or DbBasedUser (although the last one is not ideal).
• Keep interfaces, abstract classes and other entities that form cross-component interface in a separate Java package. See below for naming conventions.

Getters and Setters

• Getter and setter methods should be used only for simple properties. The invocation of getter and setter methods should not fail. Getter and setter methods should not block on a network condition (or any other condition external to the system).
• Getter and setter methods should not throw checked exceptions, and they should not throw any exception at all if possible. They in fact may throw runtime exception, but expect that the system will fail in a spectacular way if that happens.
• If you need accessor or mutator methods that could fail, give them a different name. For example retrieveFoo instead of getFoo or registerBar instead of setBar.

Best Practice

• code against interfaces, not base implementation nor other implementation classes. For example define local variable as Map map; not HashMap map;

Source Code Structure and Build

Package Names

• Use org.opendaylight.yang prefix for package names
• Prefix should be followed by component name, e.g. org.opendaylight.yang.parser
• Complex components may have sub-packages, e.g. or org.opendaylight.yang.parser.util
• Last segment of the package name (after component name) is used to distinguish public and private parts of the component. Public interfaces must be placed in a separate packages. In that case the implementation should be placed in a separate package as well. E.g. org.opendaylight.yang.service package contains public service definition, org.opendaylight.yang.service.impl contains service implementation, org.opendaylight.yang.service.mock contains mock implementation of the service. Recommended values are provided in the following table:

 

api	Public interface (that is exposed outside of component)
spi	Public interface intended for functionality providers
impl	Primary component implementation	If there are more than one implementation intended for production use, do not use this suffix. Use something that describes the implementation.
util	Utility functionality intended for ease of implementation
mock	Mock implementation for testing purposes
test	Unit tests for component