Comments 25
calculateBusinessDays
И что здесь понятно? Может тогда именовать явно: diffDates? Первоначальное название, больше говорит о какой то бизнес логике связанную с датами и днями. Но ника о том, что это просто разница в днях.
Это не разница в днях, а количество рабочих дней (исключая субботы и воскресенья) между двумя датами. Его, конечно же, можно посчитать и проще, но оставим это на совести автора.
Тут, ИМХО, вообще тонкий лёд. Что такое бизнес день? Рабочий день? Рабочий день - это вообще может быть часть часов, когда люди трудятся. А что с праздниками и переносами?
Звучит так, что я ожидаю что-то одно, а оно считает что-то другое. Или имя функции не отражает назначение, или в этой функции ошибки в расчете.
Надо было назвать getNumbeOfDaysBetweenTwoPointsOfTimeExcludingWeekend, ну или diffDatesExcludingWeekends
Ну и [SUNDAY, SATURDAY].includes(currentDayOfWeek) немного легче читать, чем предложенное условие
Переименуем fetchData в useFetchData, после чего этот хук перехочется вызывать внутри функций уже на подсознательном уровне.
У React-ивистов какой-то фетиш на префикс use? На основании чего должно перехотеться? Тем более очевидно, что данная функция не является частью React-библиотеки, и, соответсвенно, внутри может быть что угодно.
потому что есть соглашение о наименовании специального типа функций (хуков) - оно должно начинаться с префикса use. Эти хуки нельзя вызывать в функциях (технически, конечно, вам никто не запретит и где-то это даже будет работать, но есть правила в линтерах это запрещающие)
подробнее тут - https://react.dev/learn/reusing-logic-with-custom-hooks#hook-names-always-start-with-use
Имхо но в первом примере, в первом варианте код лучше выглядит. Во втором варианте есть явные проблемы.
Длинные названия переменных для читаемости тоже плохо. Необязательно каждую переменную в функции называть длинным названием, достаточно написать понятное название самой функции, т.к. всё что внутри неё инкапсулировано и имеет смысл в контексте этой функции.
Второй вариант нарушает принцип функционального программирования. Зачем выносить константы начала и конца недели в глобальную видимость, да ещё и нарушать нотацию js (вроде как) по неймингу, написав их капсом. По факту, второй вариант написан в процедурном стиле. Эти константы можно было перенести в аргументы функции, если их нужно менять или поместить их во внутрь функции.
Касаемо второго примера, то уже многие писали, что есть системные названия хуков. Если они режут глаз, можно их "обернуть" в функции с понятным названием.
Так же касаемо нейминга. useFetch это масло масленное. Есть негласно принятое правило нейминга функций/методов во всех ЯП. Первым в названии идёт глагол, вторым существительное, прилагательное и т.д. Use и fetch это два глагола. Тогда хотя бы надо было назвать функцию useFetching, а лучше назвать её по смыслу того, что делает fetch внутри. Например getUser, если fetch получает данные юзера с бэкенда.
Насчет хуков хотела бы поспорить -- речь идет конкретно о хуках в React. Эти хуки должны быть легко отличимы от функций, потому что концептуально отличаются и используются по-разному. Поэтому вариант с названием хука без use в начале -- не вариант.
Однако я согласна с тем, что useFetchData звучит не очень, уместнее было бы при таком исполнении назвать его просто useData. В целом, в названии хуков редко после use идет глагол, просто такой пример. Я хотела придумать пример, который бы продемонстрировал, как вызов хука, ошибочно принятого за функцию, может привести к ошибке, и это лучшее, что пришло мне в голову ))
Если мы откроем документацию на RTK Query, то там в самом начале будет такое:
` const { data, error, isLoading } = useGetPokemonByNameQuery('bulbasaur') `
Иными словами, это обычное дело, когда за use идет глагол с обстоятельствами действия. Когда у нас этих обстоятельств нет, то что мешает использовать useFetch?
Семантически это читается как хук для fetch.
А useData вообще ничего не говорит о семантике операции. Это же имя можно использовать для доступа к стору приложения
Название метода подразумевает какой-то расчёт, но непонятно, что он возвращает или же не возвращает ничего!
Вот такое название метода будет говорить нам, что метода что-то делает, но ничего не возвращает:
function calculateBusinessDays(startDate, endDate)
Если мы хотим показать, что метод что-то возвращает, тогда используем:
function getBusinessDays(startDate, endDate)
Мы ведь всё равно понимаем, что мы отдали что-то в метод, метод что-то сделал и вернул нам обратно - не нужно лишних слов. Нужно только одно слово - get, чтобы показать, что метод возвращает.
Далее переменную следует переименовать:
let businessDayCount = 0;
В
let businessDaysCount = 0;
businessDays - это массив/список, businessDaysCount - это его "свойство".
!!!
Дополнительно отмечу, что использование TypeScript решит большую часть проблем, в том числе проблем с пониманием кода.
С первого раза понял, что делает countDays никакой сложности не заметил
...
const [data, setData] = React.useState(null);
...
.then((data) => setData(data))
для статьи, где рассказывают о важности нейминга, именуют данные просто словом data, так еще и в рамках одной функции две переменные с тем же именем...
Например: Вы работаете с проектом, в котором множество функций и переменных имеют схожие или слишком общие названия, например, data, info, processRequest
Да, я еще думала, обратит ли кто-нибудь на это внимание. У меня был выбор, либо детально прорабатывать примеры, рассеивая фокус внимания, либо опускать некоторые детали, чтобы сфокусировать внимание на чем-то конкретном. Я решила пойти по второму пути, но многие комментаторы отписались, что примеры не очень, поэтому, видимо, они правда не очень. Буду стараться лучше!
А ведь можно просто коментировать над переменными/функциями описание, что ЭТО делает и ЧТО возвращает, а также прочие тонкости работы.
Почему-то не многие вообще заостряют внимание на комментировании исходного кода 🥴
В таком случае каждый раз, встретив вызов функции или использование переменной, надо будет смотреть на комментарии, чтобы понять, для чего эта функция или переменная нужны. Доводя до абсурда, назовём все функции func1, func2 и т.д, все переменные - var1, var2 и т.д. и будем ориентироваться только по комментариям к ним.
Код и комментарии к нему имеют нехорошее свойство со временем разбегаться, когда код правится, а на комментарии забивают. Но, сама идея описания параметров и возвращаемых значений в дополнение к правильному неймингу вполне себе используется, например, в doc-блоках PHP и JS.
1. Маленький вопрос по форме: "Но зачастую забываем о самой базовой, но критически важной вещи, без которой все эти усилия могут оказаться малоэффективными, – это хороший нейминг. " - я лет 10 работаю в разных конторах и командах и всегда все запаривались из-за выразительного именования всего, поэтому мне интересно в самом деле у автора частая проблема с такими вещами? Ошибиться в нейминге, действительно, легко, но на ревью скорее всего вам подскажут ошибку.
2. "А что насчет типизации? Возможно, подумали вы. Все верно, типизация это один из возможных способов улучшения читаемости кода." - честно говоря, данный пассаж я не понял. Если у нас обсуждение про проблемы нейминга, то каким образом к этому относится типизация сама по себе? Типизация - это такой же совершенно исходный код, который при плохом нейминге читаемость не улучшает. Иными словами, типизацию в данном контексте нужно рассматривать как и любой другой исходный код.
3. "Потому что в долгосрочной перспективе время, потраченное на нейминг, сократит время, которое иначе придется потратить на:"
- "Понимание и чтение кода." - опять брюжжание по форме, чтение и есть процесс направленный на понимание заложенной информации.
- "Рефакторинг и исправление багов. Если код понятен и выполняет свою задачу, его не нужно рефакторить. Если код не рефакторить, то в нем не появляются новые баги. " - беда в том, что все звучит настолько обобщенно, что непонятно как хороший нейминг связан с багами? Далее, если код понятен и выполняет свою задачу, его все равно по десятку различных причин можно отрефакторить и получить пользу. Иными словами, я хочу сказать как именно хороший нейминг помогает избежжать багов? Думаю, отвечая на этот вопрос вы пересечетесь с первым пунктом про читабельность кода. А замечание, что если не писать код, то и ошибок не будет, еще более общее.
4. "Мотивация" - опять, небольшое нытье по форме. Вы только что, в разделе выше описали мотивацию.
5. "Упрощение поиска" - по моему, вы не точно расставили акценты. Должен быть глоссарий предметной области, на основании которого и выбираются названния "высокоуровневых" сущностей. А есть, локальный код, который работает внутри реализации конкретной сущности. Так вот: "data, info, processRequest" - это больше походит на такие локальные сущности (кстати, в ваших примерах это отражено), которых в проекте может быть масса и в этом нет никакой проблемы. Потому что искать участок кода нужно именно по неймингу из глоссария.
6. "Хороший нейминг: Если нейминг хороший, то становится понятно, что делает эта функция, просто прочитав код." - опять замечание по форме. Если нейминг хороший, то не нужно читать код, что бы понять его назначение. Достаточно прочитать название функции. Наверное, именно это вы имели в виду.
7.
```
function useFetchData(url) {
const [data, setData] = React.useState(null);
React.useEffect(() => {
fetch(url)
.then((response) => response.json())
.then((data) => setData(data))
.catch((error) => console.error(error));
}, [url]);
return data;
}
```
Если я правитльно понял посыл вашей статьи, то это тоже не очень хорошо, потому что у вас тут везде одни сплошные `data`, а видимо должно быть типа
```
function useFetch(url) {
const [data, setData] = React.useState(null);
React.useEffect(() => {
fetch(url)
.then((response) => response.json())
.then((responseData) => setData(responseData))
.catch((fetchError) => console.error({ fetchError }));
}, [url]);
return data;
}
```
Как вы правильно заметили в начале статьи, не нужно забывать про нейминг при обсуждении в любом контексте XD
8. "Облегчение командной работы" - вы описали проблему, которая ясно дает понять, что на проекте должен быть глоссарий предметной области. А задача, которую вы описали должна быть описана не в терминах исходного кода, а в терминах предметной области. Поэтому такой фигни: "Катя: Слушай, у нас проблема с TaskList. " - быть не должно, какое бы именование там не стояло. Должно быть, что то типа: "Проблема со списком задач в таком то месте".
Эта статья для меня первая на хабре и первая по теме нейминга, поэтому я решила затронуть эту тему для начала на базовом уровне. Понятное дело, что на таком -- базовом уровне -- эта проблема остро не стоит у опытных разработчиков. Но я ее хочу разобрать более детально, и формализовать ее тоже как можно более детально. Если получится, собрать справочник или список основных принципов. Так что эта статья скорее как вводная. Чтобы ответить на ваш вопрос, то да, с проблемами нейминга я сталкиваюсь, но с более тонкими.
Я хотела взять в качестве отправной точки тему читаемости кода, почему она важна, и потом эту тему развить и прийти к тому, что нейминг это важно. Пока редактировала статью, частично удаляла, частично что-то дописывала, поэтому этот фрагмент про TS получился вырванным из контекста, согласна с вами.
т_т
т_т
Интересно, я с глоссариями именно в кодовой базе не работала, почитаю про них
Ну, не совсем. Если у функции хорошее название, но в ее теле плохой нейминг, то это все равно проблема, потому что рано или поздно придется внутрь этой функции проникать и разбираться.
Да, даа, я уже поняла :D Объясню свою мотивацию, почему тут было использовано именно название data. Потому что это абстрактный пример, и фокус в этом примере не на какой-то определенной модели данных, а на префиксе use. Конкретно в данном примере без разницы, что на месте data будет. Потому что это пример, а не рабочий код. Я почему-то решила, что такой уровень абстракции будет уместен, потому что не загрузит лишними деталями, но уже поняла, что он не был уместен :D
Ааааа я, кажется, поняла, про какой глоссарий идет речь. Да, пожалуй, вы правы, в идеале должен быть глоссарий. Но он все равно не решит все проблемы. Глоссарий отвечает за смысловое наполнение, а я хочу формализовать сам подход к составлению названий, морфологию так сказать. Эта статья должна была быть вводной к следующей :D Но анонс такой себе получился, мне теперь страшно следующую публиковать xD
Как нейминг влияет на качество кода?