Короткие, длинные, непонятные, но все комментарии. В основном это ненужные части, которые только увеличивают размер файлов, ничего не добавляя.

Привет, разработчик, в этом посте я попытаюсь продемонстрировать, что комментарии в вашем коде не нужны. Хорошо, давайте начнем.

Спустя годы я узнал о лучших практиках. И это здорово, когда самыми известными правилами являются Комментируйте свой код, включайте комментарии в свой код для большей ясности. И это не совсем так. Неплохо включать комментарии в свой код, но если вы не знаете, как правильно их включать…

Это очень сложно, не зная хороших практик по этому поводу. Начнем с очень распространенного примера.

from django.contrib.auth.models import User
from django.core.exceptions import ObjectDoesNotExist
def get_user(id):
    """
    This method use ID number to get User object.
    """
    try:
        return User.objects.get(pk=id)
    except ObjectDoesNotExist:
        return null

В этом случае комментарий можно удалить одним изменением.

from django.contrib.auth.models import User
from django.core.exceptions import ObjectDoesNotExist
def get_user_by_id(id):
    try:
        return User.objects.get(pk=id)
    except ObjectDoesNotExist:
        return null

Слушайте, если ваш код понятен, вам не нужен комментарий. get_user_by_id уже указывает, что вы получаете пользователя по его идентификатору.

def is_valid(form):
    """
    This method checks that all the values in the form are valid.
    name: string
    age: integer
    ...
    """
    if type(form['name']) not is str or not form['name'].strip():
        # Validate if name field is string and not empty.
        return false
    if type(form['age']) not is int or not form['age'] > 0:
        # Validate if age field is integer and positive number.
        return false
    ...
    return true

Хорошо, в этом случае я предлагаю две вещи. Первый параметр включен is_valid в объект Form. Если вы это сделаете, нет необходимости ставить первый комментарий, так как ясно, что он подтверждает правильность формы.

class RegisterForm():
    name = CharField(...)
    age = IntegerField(...)
 
    def is_valid():
        ...

С этим небольшим изменением подразумевается, что вы собираетесь пройти валидацию. Посмотрите на пример, как это использовать.

form = RegisterForm(data)
form.is_valid()

Второй вариант заключается в дополнительном уточнении кода. Я оставлю это для будущего поста, но этот случай поможет сделать код более тестируемым и пригодным для повторного использования.

Во-первых, нам нужно изменить is_valid, действительно ли что? например is_valid_register_form, is_valid_login_form… Это не имеет значения, но вы должны указать, что is_valid.

С другой стороны, другие комментарии делают код более запутанным. С моей точки зрения, это должно превратиться в новые функции. Таким образом, это поможет нам сделать код более понятным и удобным для тестирования.

def is_valid_name(name):
    return type(name) is str and name.strip()
def is_valid_age(age):
    return type(age) is int and age > 0
def is_valid_register_form(form):
    if (
        not is_valid_name(form['name'])
        or not is_valid_age(form['age'])
        ...
    ):
        return false

    return true

Теперь легче читать код. И не нужно комментариев, чтобы понять. Если вам нужно пройти следующий уровень, я предлагаю другое изменение. Добавьте новую карту валидатора, чтобы было удобнее разбираться и редактировать код. Использование переменных конфигурации помогает понять и облегчить будущие изменения в коде, как в этом случае, для сопоставления всех проверок формы.

def is_valid_name(name):
    return type(name) is str and name.strip()
def is_valid_age(age):
    return type(age) is int and age > 0
VALIDATOR_MAP = {
    'name': is_valid_name,
    'age': is_valid_age,
}
def is_valid_register_form(form):
    errors = []
    
    for field_name, field_validator in VALIDATOR_MAP.items():
        if not field_validator(form[field_name]):
            errors.append('Error in {} field'.format(field_name))
    return errors

Выберите вас, чтобы хотеть метод. И не забывайте избегать ненужных комментариев кода.