7. Комментарии

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 для создания коммитов с объяснением, почему код был закомментирован или удален. Это обеспечит более чистую, читаемую и управляемую историю вашего кода.