Coding Standard

⚠️ In progress

We aim for:

• Code maintainability
• Low coupling and high cohesion
• Simplicity (don't overengineer)

VDK coding styles aim for code style and formatting consistent across its components. The value of consistency is enabling automated formatting, avoiding back and forth reformatting, and making the code easy to read for all team members.

REST API and Services

We follow 12 factor app recommendation for building web/api services

TODO: ideas: https://opensource.zalando.com/restful-api-guidelines/#100

Java

TODO: maybe https://google.github.io/styleguide/javaguide.html

Python

The coding standard is the Python regular PEP 8. It's enforced by pre-commit hooks like black

Clarification on access modifiers in python

Python uses _ (underscore) symbol to determine the access control for a specific data member or a member function of a class

• Public methods have not underscore prefix
• Protected methods or attributes have single underscore as prefix - for example _execute_protected()
• Private methods or attributes have double underscore as prefix - for example __execute_private()

Public Python interfaces

Any backwards compatibility guarantees apply only to public interfaces. Public interfaces are modules and packages defined or imported in vdk.api.*. unless the documentation explicitly declares them to be provisional or internal interfaces. Anything else is considered internal. All public interfaces (classes or methods) must have documentation.

CLI (Command Line interfaces)

CLI is built following 12 Factor CLI Apps

Error handling

Do not explain your (the developer) problem. Explain their (the user, and sometimes the caller) problem, and provide info valuable for THEM to understand what actions to take.

For more details see https://github.com/vmware/versatile-data-kit/blob/main/projects/control-service/CONTRIBUTING.md#error-handling

README files

Each VDK project or plugin has a README file that resides in its root folder and is named README.md.

A README file is written in Markdown.

A README file of a project or a plugin should contain (whichever applicable):

• what the project is about (e.g. its purpose)
• how to install the project (e.g. how to install its dependencies)
• how to configure the project (e.g. where the configuration file resides, and what each configuration property means)
• how to build the project (e.g. how to compile its source code)
• how to use it (e.g. what command to execute and examples)