Называние: Вы должны пожертвовать краткостью для ясности?

11

Например, следующая функция перебирает массив, который содержит имя и ошибки поля ввода. Это делается путем проверки имени проверяющего поля, а затем отправки информации об ошибке в массив неверных полей.

Лучше быть кратким и написать это:

addInvalidField (field, message) {
  const foundField = this.invalidFields.find(value => {
    return value.name === field.name
  })
  const errors = foundField.errors
  if (!errors.some(error => error.name === message)) {
    errors.push({ name: message, message })
  }
},

Или быть более конкретным, как это?

addInvalidField (validatingField, message) {
  const foundField = this.invalidFields.find(invalidField => {
    return validatingField.name === invalidField.name
  })
  if (!foundField.errors.some(foundFieldError => foundFieldError.name === message)) {
    fouldField.errors.push({ name: message, message })
  }
},
Алекс
источник
1
связанный (возможно, дубликат): есть ли оправдание коротким именам переменных?
Комнат
Не хочется писать ответ, но мы всегда стараемся найти хороший компромисс между длиной имени и ясностью. Короткие имена могут быть очевидны для оригинального программиста, но не для всех остальных. Длинные имена могут затруднить чтение кода. Между ними есть компромисс.
MetalMikester
1
нужно больше комментариев
Ewan
Примечание, и не уверен, возможно ли это в вашем коде, но если invalidFields и т. Д. Были сохранены в карте , а не в массиве , этот код станет намного проще.
user949300
1
@alex В ответ на ваш комментарий: Если вы можете получить или одолжить копию Eloquent JavaScript от Marijn Haverbeke, (версия 2014 года), перейдите на страницы 73-75, чтобы увидеть отличный пример использования карты вместо массива. Надеюсь, это поможет.
user949300

Ответы:

23

Если краткость может быть принесена в жертву для ясности, она должна. Но если многословие можно пожертвовать ради ясности, даже лучше.

addInvalidField (field, message) {
  const foundInvalidField = this.invalidFields.find(x => x.name === field.name)
  if (!foundInvalidField.errors.some(x => x.name === message)) {
    foundInvalidField.errors.push({ name: message, message })
  }
},

Когда переменная живет только одну строку, она может быть очень короткой. FoundInvalidFieldиспользуется в трех строках и является предметом данной работы. Это заслуживает пояснительного названия.

Как всегда, контекст - это король.

candied_orange
источник
2
+1 за «Если краткость можно пожертвовать ради ясности, она должна. Но если многословие можно пожертвовать ради ясности, даже лучше». Даже когда я стремлюсь к ясности почти в каждом случае. Но это определенно цитата.
Тулаинс Кордова
12

Я на самом деле одобряю ваш первый пример кода.

Понятно, что делает код, просто читая его. Сохраняя имена переменных как можно меньше, вы делаете код еще проще для чтения. Более описательные имена переменных понадобятся только в том случае, если ваши функции будут длиннее, ваши переменные будут более многочисленными и / или переменные будут использоваться в большей области кода.

Это потому, что вы сохранили свои функции краткими, что вы также можете держать ваши имена переменных краткими. При прочих равных условиях лучше всегда меньше кода.

Роберт Харви
источник
2
Чтобы прокомментировать это, как правило, я предпочитаю меньшие имена переменных для моих методов / функций. Единственный раз, когда я бы использовал более подробное имя, - это конфликт пространства имен. Если размер вашей функции невелик, этого также легче достичь.
открывается
4
Я работал с кем-то, кто был действительно большим в подробных именах. имена переменных и методов были в основном полными английскими предложениями, например theResultOfMethodDoFooWithBar. Идея заключалась в том, что это должно было прояснить ситуацию, но у меня болела голова, пытаясь (мысленно) разобрать весь этот пух. Для этого примера мы уже знаем, что метод о проверках полей. Других «полевых» параметров нет. Использование имени типа validatingField не добавляет ясности и затеняет важную информацию при скимминге.
JimmyJames
@unflores Я тоже пытаюсь это сделать. validatingFieldsполя формы с проверкой Первоначальное имя было fieldWithValidation. Очень сложно найти короткое имя для этого. Я мог бы назвать это просто, fieldно тогда это будет конфликтовать с другим fieldвнутри метода.
Алекс
4

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


Ну, я цитирую Чистый код здесь (пропустите его, если вам надоела проповедь дяди Боба (а я нет):

Используйте намеренно раскрывающие имена

Легко сказать, что имена должны раскрывать намерения. Мы хотим произвести на вас впечатление, что мы серьезно относимся к этому. Выбор хороших имен требует времени, но экономит больше, чем требуется. Так что позаботьтесь о своих именах и поменяйте их, когда найдете лучшие. Каждый, кто читает ваш код (включая вас), будет счастливее, если вы это сделаете.


Избегайте дезинформации

Программисты должны избегать ложных подсказок, которые затемняют смысл кода. Мы должны избегать слов, укоренившиеся значения которых отличаются от наших


Делайте значимые различия

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


Использовать доступные для поиска имена

Используйте имена, которые помогут вам сделать grep -iIR whateveryouaresearching . (не Чистый код, здесь CC говорил только о однобуквенных переменных).


Избегайте умственного картографирования

Читатели не должны мысленно переводить ваши имена в другие имена, которые они уже знают. Эта проблема обычно возникает из-за выбора не использовать ни термины проблемной области, ни термины области решения.


Используйте проблемные доменные имена

Если для того, что вы делаете, не существует «программиста», используйте имя из проблемного домена. По крайней мере, программист, который поддерживает ваш код, может спросить эксперта в области, что это значит.


Тулаинс Кордова
источник
1

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

Еще в предыстории у вас были ограничения на имена переменных, и использование значимых имен переменных могло на самом деле приносить измеримую стоимость (например, в BBC BASIC с использованием целочисленных статических переменных A% и т. Д. Было намного дешевле, чем при использовании значимого целого числа - и в системе с 1 МГц процессор, сохранение нескольких тактов в цикле действительно имеет значение)

mcottle
источник
6
Недостатком является то, что вам не нужно много печатать. Набор текста происходит только один раз. Недостатком слишком длинных имен является то, что чтение становится сложнее. И это коварно, потому что чтение происходит много раз в течение жизни базы кода, а также потому, что люди не осознают источник проблемы, потому что чтение настолько укоренилось.
Килиан Фот
И если вам придется тратить время и изменения контекста, пытаясь вспомнить что-то о переменной, потому что она недостаточно описательна, это будет стоить вам больше времени :).
Маккотл
1

Второй вариант выглядит меня озадаченным. Когда я смотрю только на подпись, мне интересно, является ли поле уже известным как недействительное? Или он будет сначала проверен (как он называется validatingField), чтобы выяснить, действительно ли он недействителен? Так что это не просто избыточная информация здесь, дополнительная информация, кажется, несколько вводит в заблуждение. Этот вид «ясности» не яснее, а наоборот.

На самом деле, когда я увидел твою первую функцию, я тоже озадачился. Я спросил себя, какого чёрта ваша функция просто берет поле, но потом не использует его и ищет другое invalidFields? Поиск поля, кажется, имеет больше смысла, когда дается только имя поля, например:

addInvalidField (fieldname, message) {
  const foundField = this.invalidFields.find(value => {
    return value.name === fieldname
  })
  const errors = foundField.errors
  if (!errors.some(error => error.name === message)) {
    errors.push({ name: message, message })
  }
}

Тем не менее, я думаю, что Боб Мартин, вероятно, пошел бы дальше и сделал бы код более подробным - для большей ясности - в другом направлении. Типичный рефакторинг в духе книги «Чистый код», вероятно, будет выглядеть так:

addInvalidField (fieldname, message) {
  const foundField = findInvalidField(fieldName)
  addMessageForInvalidField(foundField,message)
}

с тремя дополнительными функциями

  findInvalidField(fieldname){
    return this.invalidFields.find(value => { return value.name === fieldname })
  }

  addMessageForInvalidField(field,message){
    const errors = field.errors
    if (!doesErrorsContain(message)) {
      errors.push({ name: message, message })
    }
  }

  doesErrorsContain(message){
     return errors.some(error => error.name === message)
  }

Это спорно, если это окупается идти так далеко с единым принципом ответственности. На самом деле есть плюсы и минусы. Моя личная точка зрения заключается в том, что исходный код является "достаточно чистым" для большей части производственного кода, но переделанный лучше.

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

Док Браун
источник
validatingFieldsполя в форме, которые имеют проверку. Первоначально я назвал их, fieldsWithValidationно это было немного долго.
Алекс
0

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

Лично мне больше нравится первый пример. Это прямо и точно, даже если переменные не имеют таких описательных имен, как во втором примере. Честно говоря, имена переменных во втором примере, на мой взгляд, не намного яснее, чем первый, а краткость функции облегчает понимание самой функции.

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

Дом
источник