Лучшие практики написания чистого и поддерживаемого кода

Лучшие практики написания чистого и поддерживаемого кода

Семь рекомендаций, которые помогут вам писать более качественный код.

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

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

1. Следуйте согласованному стилю кодирования

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

Крайне важно соблюдать следующие правила:

• Соглашения об именах (переменные, функции, классы и т. д.)
• Отступ (пробелы против табуляции, размер отступа)
• Пробелы между токенами
• Перенос строки
• Ширина печати

Последовательный стиль кодирования сделает ваш код более читабельным и понятным даже для разработчиков, плохо знакомых с проектом. Последовательность важна, потому что у всех нас есть мнения — всем нравится следовать своим собственным правилам. Но при работе над проектом в команде у вас должны быть рекомендации, объективно определяющие стиль написания кода.

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

Согласованность можно обеспечить с помощью таких инструментов, как линтеры и средства форматирования. Линтеры проверяют код на наличие ошибок, предупреждений, спецификаций стиля или лучших способов написать тот же код; некоторые IDE называют это «проверкой кода». Средство форматирования исправляет пробелы, отступы и незначительные синтаксические проблемы/настройки.

2. Пишите четкий и лаконичный код

Один из важнейших принципов написания чистого и поддерживаемого кода — сделать его ясным и кратким. Избегайте использования слишком сложного кода или вложенных условий, которые трудно понять.

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

Вот два фрагмента, которые передают четкий и лаконичный код.

// ✅ Do this
function mean(numbers: double[]) {
    var sum = 0
    numbers.forEach(n => sum += n)
    return sum / numbers.length
}

// ❌ Don't do this
function mean(numbers: double[]) {
    var sum = 0
    for (var i = 0; i < numbers.length; i++) {
        sum += numbers[i]
    }
    return sum / numbers.length
}
        

Хотя первый вариант может работать немного медленнее (из-за forEach), чтение, запись и понимание намного проще. Расширение, использование или тиражирование в будущем будет намного проще.

3. Избегайте магических чисел и строк

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

Вместо этого используйте константы или переменные для определения этих значений и предоставьте четкую документацию, объясняющую их назначение. Представьте, что вы видите это повсюду в своем коде:

if (response.status == 200)
    console.log(response.data)

Этот код создает несколько проблем:

• Не все могут знать (или вы можете забыть), что код состояния HTTP 200 является успешным HTTP
• Из контекста не всегда может быть ясно, что мы проверяем коды состояния HTTP.
• Что, если коды состояния HTTP изменятся? (они, вероятно, не будут, но другие вещи, которые вы используете, могут)
• Что, если другой разработчик неправильно его прочтет или неправильно введет код состояния где-то еще в программе?

Эти проблемы можно легко исправить, используя константы или перечисления:

// Constant method
const HttpSuccess = 200;

if (response.status == HttpSuccess)
    console.log(response.data)
// Enum method
enum HttpStatus {
    Success,
    NotFound,
    Unauthorized
    // More values here
}

if (response.status == HttpStatus.Success)
    console.log(response.data)

4. Используйте содержательные комментарии

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

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

❌ Вот пример слишком большого количества информации в комментарии:

function sum(numbers: number[]) {
    // Initially, assign the sum to 0
    let sum = 0  // This will be incremented later
    // Iterates over each element in numbers
    numbers.forEach(n => sum += n) // adds each element to sum
    return sum // Return the sum of the elements in number
}

❌ Вот пример слишком мало информации в комментарии:

function getCurrentWeather(location: string) {
    const request = new WeatherRequest()
    request.geo = WeatherAPI.getLatLong(location)
    request.forecast = WeatherForecast.Current
    request.fields = ['hi', 'lo', 'description']
    const response = await request.submit()
    return { ...response.current }
}

✅ Вот пример правильного количества информации в комментарии:

/**
  * Gets the current weather for a provided location
  *
  * @param location - A city, state, or zip code
  * @returns An object containing the high and low temperature
  *          and the description of the weather.
**/
function getCurrentWeather(location: string) {
    const request = new WeatherRequest()

    // Set the location to the corresponding geo-coordinates
    request.geo = WeatherAPI.getLatLong(location)

    // Only retrieve the current weather forecast
    request.forecast = WeatherForecast.Current

    // Only obtain the hi/lo temps, and the weather description
    request.fields = ['hi', 'lo', 'description']

    // Submit the response
    const response = await request.submit()

    // Expand the `response.current` object
    return { ...response.current }
}

Этот код более сложный, использует сторонний API, поэтому требует дополнительной документации. Важно помнить, что лучше всего использовать соответствующее количество комментариев. Простой код, вероятно, не потребует пояснений; ни один из них не будет общепонятным кодом.

5. Тщательно протестируйте свой код

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

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

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

6. Используйте контроль версий

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

Используйте систему контроля версий, такую ​​как Git, для управления своим кодом и убедитесь, что вы часто фиксируете изменения и пишете четкие и краткие сообщения о фиксации.

7. Регулярно проводите рефакторинг своего кода

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

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

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

Если вам понравилось читать эту статью, пожалуйста, ознакомьтесь с некоторыми из моих других статей:

Дополнительные материалы на PlainEnglish.io.

Подпишитесь на нашу бесплатную еженедельную рассылку новостей. Подпишитесь на нас в Twitter, LinkedIn, YouTube и Discord .