Perform Engineering Excellence

[temanbrcom]

Description

As a software engineer, I would like to have my code aligned to the code excellence standards so I can easily maintain code and introduce new features

Acceptance criteria

• The code is aligned to the defined code style and naming convention (see below)
• The packages are renamed to represent the Broadcom branding

Code style guide

1. Interface names should not contain any markers (like "I" at the start) because it is not necessary for clients to know that type is an interface. Implementations should contain the interface name and a word that describes the purpose of this class, or "Impl" at the end if it is planned to have only one implementation at the moment (only if you cannot imagine something more descriptive).
   For example, CobolTextDocumentService implements TextDocumentService.

2. If some class implements some pattern (i.e Singleton, Strategy, etc.) then it should be specified in the name.
   For example, CobolErrorStrategy.

3. Class names should not be too generic or contain some "er"-words - Manager, Server, etc. unless it is some specification or domain requirement.
   For example, MessageManager is bad, Messages is good. If you have a problem with naming, maybe you should split the class, to let every part have only one purpose or abstraction level.

4. Methods should contain only one responsibility and one abstraction level. Also, the names should be descriptive.

5. Each public method should have a Javadoc comment that describes the parameters and the results (i.e. does it accept or return null if it may be important, that checks for the parameters does it apply). Also, if there is some complicated logic, it should be described in the comment. The best practice would be also to add code examples to the class Javadoc comment.

6. There should be no author section at the comments.

7. Unit tests that are use cases should contain the description and purpose of the case.

8. You should avoid in-code comments unless it is necessary.

9. Try to use as fewer method parameters as you can. The best practice is to make the method name describing why the parameters are necessary, for example - getUserBy(long id).
   Avoid (until is not strictly necessary) to pass null as parameter

10. Always extract complicated logical sentences.

11. Use Lombok where it is possible to reduce boilerplate code.