7. Комментарии
7.1. Общие договоренности
⚠️
- Комментарий нужен не для того чтобы сделать хороший код.
- Комментарий нужен для того чтобы его пояснить.
- Если в коде 💩💩💩, то нужно исправлять код, а не писать к нему хороший поясняющий комментарий
Общие рекомендации по написанию комментариев
- Не используйте комментарии для описания очевидного. Комментируйте только те блоки кода, которые могут быть непонятными или сложными для других разработчиков
- Избегайте написания слишком много комментариев. Слишком много комментариев может сделать код неразборчивым и трудным для чтения
- Если кусок кода взяли с интернета (stackoverflow, medium и пр.), то не стесняйтесь оставить ссылку в том месте где это используется. Например (opens in a new tab)
- Пишите комментарии на английском языке
- Для написания комментариев пользуйтесь JSDoc (opens in a new tab)
👎 Примеры плохих комментариев:
todolists-reducer.ts
export type InitialStateType = {
// происходит ли сейчас взаимодействие с сервером
status: RequestStatusType
// если ошибка какая-то глобальная произойдёт - мы запишем текст ошибки сюда
error: string | null
// true когда приложение проинициализировалось (проверили юзера, настройки получили и т.д.)
isInitialized: boolean
}
export const removeTodolistTC = (todolistId: string) => {
return (dispatch: ThunkDispatch) => {
//изменим глобальный статус приложения, чтобы вверху полоса побежала
dispatch(setAppStatusAC("loading"));
//изменим статус конкретного тудулиста, чтобы он мог задизеблить что надо
dispatch(changeTodolistEntityStatusAC(todolistId, "loading"));
todolistsAPI.deleteTodolist(todolistId)
.then((res) => {
dispatch(removeTodolistAC(todolistId));
//скажем глобально приложению, что асинхронная операция завершена
dispatch(setAppStatusAC("succeeded"));
});
};
};
👍Пример хорошего комментария:
handleServerNetworkError.ts
/**
* Handles network errors from the server and dispatches an action to set the app error.
*
* @param {unknown} err - An error that occurred when sending a request to the server.
* @param {AppDispatch} dispatch - The dispatch function from the Redux store.
* @returns {void}
*/
const handleServerNetworkError = (err: unknown, dispatch: AppDispatch): void => {
let errorMessage = 'Some error occurred'
if (axios.isAxiosError(err)) {
errorMessage = err.response?.data?.message || err?.message || errorMessage
} else if (err instanceof Error) {
errorMessage = `Native error: ${err.message}`
} else {
errorMessage = JSON.stringify(err)
}
dispatch(appActions.setAppError({ error: errorMessage }))
}
7.2. Не оставлять закомментированные участки кода
Оставление закомментированного кода в репозитории является плохой практикой по нескольким причинам:
- Ухудшение читаемости кода: Закомментированный код может сделать ваш код менее читаемым. Когда разработчики читают ваш код, им приходится пропускать закомментированный код, что усложняет понимание того, как работает программа.
- Избыточность: Если код был закомментирован, но больше не используется, это создает избыточность и лишний балласт в вашем репозитории. Он занимает место и может затруднить поиск и обслуживание актуального кода.
- Путаница и ошибки: Закомментированный код может создавать путаницу и ошибки. Например, если разработчик случайно раскомментирует участок кода, не понимая его назначения, это может привести к непредсказуемым проблемам и багам.
- Отсутствие актуализации: Код в репозитории должен быть актуальным и рабочим. Если код закомментирован, его обновление может быть забыто, и он останется устаревшим.
Итого:
Лучше всего удалять закомментированный код, если он больше не используется, и оставлять комментарий или использовать систему контроля версий (например, Git) для отслеживания изменений.
❗ Если вам действительно нужно сохранить старый код для будущего использования или для истории, лучше использовать Git для создания коммитов с объяснением, почему код был закомментирован или удален. Это обеспечит более чистую, читаемую и управляемую историю вашего кода.