-
Notifications
You must be signed in to change notification settings - Fork 56
Coding Standard
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 contributors.
We follow 12 factor app recommendation for building web/api services. Make sure you have read and are familiarized with the document.
The rules outlined in https://opensource.zalando.com/restful-api-guidelines/ are recommended read and nice to follow but not a must.
We follow Google Java Coding style and it is enforced by a pre-commit hook.
The coding standard is the Python regular PEP 8. It's enforced by pre-commit hooks like black.
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()
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 is built following 12 Factor CLI Apps. Make sure you have read and are familiarized with the document.
Summarized those are:
- Great help is essential. Every command and option should have detailed help and examples.
- Prefer flags (key/value input) to arguments (positional input)
- Version option/comand
- Stdout is for data and output and stderr is for logs and messages!
- Make errors informative. Basically follow VDK error guidelines
- Be fancy if you can
- Prompt if you can
- Use tables but allow output in csv or json
- Be speedy (< 1 second respond time!)
- Encourage contributions
- Be clear about subcommands
- Follow XDG-spec for config or data files.
Errors should not explain our (the developer) problem. Explain their (the user, and sometimes the caller) problem, and provide info valuable for THEM to understand what actions to take.
Make sure you have read: https://github.com/vmware/versatile-data-kit/blob/main/projects/control-service/CONTRIBUTING.md#error-handling
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).
SDK - Develop Data Jobs
SDK Key Concepts
Control Service - Deploy Data Jobs
Control Service Key Concepts
- Scheduling a Data Job for automatic execution
- Deployment
- Execution
- Production
- Properties and Secrets
Operations UI
Community
Contacts