-
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. The documentation must specify clearly:
- What is the purpose of the method/class
- What are the possible effects and side effects
- For each argument what are the preconditions
- Example usages
Each python project (for example a vdk plugin) should be classified based on its development status.
In setup.py (or setup.cfg) define classifier "Development Status" as defined in https://pypi.org/classifiers.
The semantics of the "Development Status" classifier same as one defined in https://martin-thoma.com/software-development-stages
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 follow Error handling format which aims to help write clearer and more consistent error messages.
Each VDK project or plugin has a README file that resides in its root folder and is named README.md. Each independentally releasable sub-component (e.g plugin, job-builder, job-base image) must have a README file as well.
A README file is written in Markdown.
A README file of a project or a plugin should contain (whichever is applicable):
- what the project is about (e.g. its purpose);
- how to install the project (e.g. how to install and configure 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