Короткие, длинные, непонятные, но все комментарии. В основном это ненужные части, которые только увеличивают размер файлов, ничего не добавляя.
Привет, разработчик, в этом посте я попытаюсь продемонстрировать, что комментарии в вашем коде не нужны. Хорошо, давайте начнем.
Спустя годы я узнал о лучших практиках. И это здорово, когда самыми известными правилами являются Комментируйте свой код, включайте комментарии в свой код для большей ясности. И это не совсем так. Неплохо включать комментарии в свой код, но если вы не знаете, как правильно их включать…
Это очень сложно, не зная хороших практик по этому поводу. Начнем с очень распространенного примера.
from django.contrib.auth.models import Userfrom 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 Userfrom 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 andage
> 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 andage
> 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
Выберите вас, чтобы хотеть метод. И не забывайте избегать ненужных комментариев кода.