Working with Source Code
This section contains our rules for working with source code, which we try to follow on all our projects.
Code formatting is important. You spend far more time reading code (both your own and other people's) than you doing writing it. When the code is written in a good, uniform style, it's much easier to read, and more enjoyable too. The eyes don't have to "stumble" all over the text and the reader can quickly grasp the code's essence.
The names of all file, variables, and data structures should be in English. Additionally, all functions, parameters, classes, methods, comments, basic documentation, database tables and fields, commit headers, branch names, etc. must be strictly in English. Try to write competently. Correct any errors or misprints that you notice.
Naming can be difficult. But that's the way it has to be :). Whatever you name (a variable, a file, a commit, a section in the documentation, or anything else), try to make the name as clear and easy to read as possible. All things being equal, concise names are better than long names, but brevity should not come at the expense of clarity and readability.
Take, for example, these two commit messages:
- "Small fixes" <- Not good. What is the essence of the commit? It is not clear which part of the system these "fixes" refer to, nor what exactly was fixed;
- "Fixed typo in registration page title" <- Perfect. The nature of the fix and the place where it was applied are immediately clear.
- Python - PEP 8, our maximum string length is 80 characters. See also Style corrections by David Cramer. We use Flake8 and isort to automatically check the code.
- JavaScript - Airbnb JavaScript Style Guide. We use ESLint to check the code.
- HTML/CSS - Google HTML/CSS Style Guide.
- PHP - we don't have any projects in PHP, but we have to deal with it sometimes. If you need to write in PHP, start with PHP: The Right Way.
A new developer who connects to your project should be able to figure out for themselves what this project does in general and how to contribute. If the project has a public API, describe how to use it, at least the most important parts.
- Keep all your work on the project in the repository. Documentation, wikis, server settings, deployment scripts, and utilities are much more convenient when all this is gathered in one place and versioned.
- Avoid duplication. Do not include anything in your repo that can be obtained from other sources. For example, you should not include compiled files, because they can be obtained by compiling from source. Do not include third party libraries, use package managers, such as pip, npm, etc.
- Commit atomically and with descriptive messages. This is a key principle to ensure that the project history is easily readable, and it facilitates the code review. Each commit must contain one logical change in the project, such as the implementation of a feature, or a bug fix. The commit's title should be brief but clear about what it does (see "Think of Good Names" above).
- The length of the commit title must be limited at 72 characters. Longer titles are truncated by GitHub when viewing the history.
- Use rebase instead of merge whenever possible. This also improves the readability of the history.
Do not leave any commented or unused code blocks in the project. If in the future you need to see an older version of the code, or to roll a commit back, you have version control for that.
If you include third-party source code or components in a project, please be sure the license allows it.
Also, the code that you write for your work is owned by your employer, and may not be disclosed or used in third party projects without explicit permission.
English
Русский