Что такое Google code style?

Google Code Style для Python

Что такое Google Code Style

Google Code Style (или Google Style Guide) — это набор рекомендаций по написанию чистого, читаемого кода. Google разработал стайлгайды для основных языков программирования, включая Python. Это не обязательный стандарт, но industry best practice, который используют многие компании.

История и актуальность

• Впервые опубликован Google в 2009 году
• Постоянно обновляется (последняя версия — 2023)
• Используется Google, а также многими tech-компаниями
• В контексте Python часто дополняется PEP 8

Основные принципы Google Style Guide

1. Читаемость превыше всего

# ❌ Трудно читать
def fn(a,b,c):
    return a+b+c if a>0 and b>0 and c>0 else 0

# ✅ Google Style: ясная читаемость
def calculate_sum(first_number, second_number, third_number):
    """Вычисляет сумму трёх положительных чисел.
    
    Args:
        first_number: Первое число
        second_number: Второе число
        third_number: Третье число
    
    Returns:
        Сумма чисел, или 0 если любое число отрицательное
    """
    if all(n > 0 for n in [first_number, second_number, third_number]):
        return first_number + second_number + third_number
    return 0

2. Docstrings (документирование функций)

Google требует Google-style docstrings, а не NumPy или другие форматы:

def fetch_user_by_email(email: str, db_session) -> dict | None:
    """Получает пользователя по email из БД.
    
    Это однострочное описание (summary). На этой же строке может быть краткое
    объяснение, если оно очень короткое.
    
    Более подробное описание идёт отдельным абзацем, если нужно объяснить
    сложные детали или особенности функции.
    
    Args:
        email: Email адрес пользователя (строка, валидная почта)
        db_session: SQLAlchemy session для работы с БД
    
    Returns:
        Словарь с данными пользователя:
        {
            'id': int,
            'email': str,
            'name': str,
            'created_at': datetime
        }
        или None если пользователь не найден.
    
    Raises:
        ValueError: Если email некорректный
        DatabaseError: Если ошибка подключения к БД
    
    Examples:
        >>> user = fetch_user_by_email('john@example.com', db)
        >>> print(user['name'])
        'John Doe'
        
        >>> non_existent = fetch_user_by_email('nobody@example.com', db)
        >>> print(non_existent)
        None
    """
    if not is_valid_email(email):
        raise ValueError(f"Invalid email: {email}")
    
    user = db_session.query(User).filter(User.email == email).first()
    return user.to_dict() if user else None

3. Импорты

# ✅ Google Style импорты
# 1. Стандартная библиотека
import os
import sys
from datetime import datetime
from typing import Optional, Dict, List

# 2. Третьесторонние библиотеки
import requests
from sqlalchemy import Column, String
from flask import Flask, request

# 3. Локальные импорты
from app.models import User
from app.utils import logger

# ❌ Плохо: смешанные импорты
import os, sys, requests
from datetime import datetime
from app.models import User
import flask

4. Именование

# Переменные и функции: snake_case
user_name = "Ivan"
def calculate_total_price(): pass

# Классы: PascalCase
class UserManager: pass
class DatabaseConnection: pass

# Константы: UPPER_SNAKE_CASE
MAX_RETRIES = 3
DEFAULT_TIMEOUT = 30
API_BASE_URL = "https://api.example.com"

# Приватные: _leading_underscore
class DataProcessor:
    _internal_buffer = []
    def _validate_input(self): pass
    
# Очень приватные: __double_leading
class SecureStorage:
    __encryption_key = "secret"

5. Длина строк

# Google Style: максимум 80 символов (некоторые позволяют 100)

# ✅ Правильно: разбитая длинная строка
result = some_function_with_long_name(
    first_parameter,
    second_parameter,
    third_parameter
)

# ✅ Правильно: продолжение с отступом
query = (
    session
    .query(User)
    .filter(User.active == True)
    .filter(User.email.like('%@example.com'))
    .order_by(User.created_at.desc())
)

# ❌ Плохо: одна длинная строка
result = some_function_with_long_name(first_parameter, second_parameter, third_parameter)

6. Типизация (Type Hints)

Google требует полную типизацию для всех публичных функций:

from typing import Optional, List, Dict, Tuple, Union

# ✅ Google Style: полная типизация
def process_user_data(
    user_id: int,
    filters: Dict[str, str] | None = None,
    limit: int = 100
) -> List[Dict[str, any]]:
    """Обрабатывает данные пользователя с фильтрами."""
    pass

# ✅ Сложные типы
def fetch_data(
    ids: List[int],
    config: Dict[str, Union[str, int, bool]]
) -> Tuple[List[Dict], int]:
    """Возвращает данные и количество результатов."""
    pass

# ❌ Плохо: без типов
def process_user_data(user_id, filters=None, limit=100):
    pass

7. Линия пустоты

# ✅ Google Style: правильное использование пустых строк

import os  # Импорты вверху
from datetime import datetime

# Пустая строка между импортами и кодом

MAX_SIZE = 100  # Константы
DEFAULT_VALUE = 0

# Пустая строка перед классом

class UserManager:
    """Управление пользователями."""
    
    def __init__(self, db):
        self.db = db
    
    # Пустая строка между методами
    def create_user(self, name: str) -> dict:
        """Создаёт пользователя."""
        user = {"name": name}
        self.db.insert(user)
        return user
    
    # Пустая строка между методами
    def delete_user(self, user_id: int) -> bool:
        """Удаляет пользователя."""
        return self.db.delete(user_id)

# Две пустые строки перед следующей функцией

def utility_function():
    """Утилита."""
    pass

8. Обработка исключений

# ✅ Google Style: специфичная обработка
try:
    user = fetch_user_from_db(user_id)
except UserNotFoundError:
    logger.warning(f"User {user_id} not found")
    user = None
except DatabaseConnectionError as e:
    logger.error(f"DB connection failed: {e}")
    raise

# ❌ Плохо: ловля всех исключений
try:
    user = fetch_user_from_db(user_id)
except Exception:  # Ловит ВСЕ исключения!
    user = None

9. List comprehensions и генераторы

# ✅ Google Style: простые list comprehensions OK
quared_numbers = [x ** 2 for x in numbers]

# ✅ Многострочные — лучше функция
active_users = [
    user for user in users
    if user.is_active
    if user.created_at > date_threshold
    if user.email_verified
]

# ✅ Сложные — лучше функция
def get_active_verified_users(users, threshold):
    """Возвращает активных, проверенных пользователей."""
    return [
        user for user in users
        if user.is_active
        and user.email_verified
        and user.created_at > threshold
    ]

# ❌ Плохо: слишком сложный list comprehension
result = [[x*y for x in range(5)] for y in range(5)]

Сравнение: Google Style vs PEP 8

Инструменты для Google Style

# Проверка соответствия Google Style
# 1. pylint (с Google конфигом)
pylint --load-plugins=pylint_google app/

# 2. flake8 с расширениями
flake8 --config .flake8 app/

# 3. black (автоформатирование)
black --line-length 88 app/

# 4. mypy (проверка типов)
mypy --strict app/

# 5. Google's Python Style Guide лinter
# https://github.com/google/google-style-guide

Пример конфига для проекта

# .pylintrc (для Google Style)
[MASTER]
max-line-length=88
load-plugins=pylint_google

[DESIGN]
max-attributes=7
max-arguments=5

[MESSAGES CONTROL]
disable=missing-docstring

# pyproject.toml
[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

Итог

Google Code Style — это не просто набор правил, это философия письма кода:

• Читаемость важнее всего
• Типизация обязательна
• Документирование — святое
• Простота лучше магии

Хотя это Google's руководство, похожие принципы используют Meta, Microsoft, Apple. Следование Google Style делает код профессиональным, поддерживаемым и понятным для новых разработчиков.