Кава-брейк #103. На захист “Чистого коду”: 100 вічних порад

Джерело: Hackernoon "Чистий код" Роберта К. Мартіна - сама рекомендована книга з програмування всіх часів. Пошукайте книги за запитом “найкращі книги для розробників програмного забезпечення” та майже гарантовано знайдете цю книгу у пошуковій видачі. І хоча деякі люди вважають, що на книгу “Чистий код” не варто звертати увагу, я сказав би, що подібні настрої глибоко помилкові. Так, деякі поради у книзі сумнівні. Так, частина контенту здається застарілою. Так, деякі приклади збивають з пантелику. Все це правда. Але давайте не будемо так швидко скидати з рахунків безліч корисних порад, які пропонує ця книга! Повне ігнорування "Чистого коду" просто через кілька поганих ідей - не найкраще рішення. Отже, давайте без зайвих слів розглянемо найкращі поради, які пропонує нам книга Clean Code! Ми пройдемося по кожному розділу, підсумовуючи ідеї, які пропонує дядько Боб та його співавтори.

Глава 1: Чистий код

1. Загальна кількість безладу з часом зростає.

2. Відновити застарілу систему дуже складно. Рефакторинг та поступові поліпшення стануть найкращим для цього варіантом.

3. У заплутаній кодовій базі виконання завдань, які мають займати лише кілька годин, можуть піти дні чи тижня.

4. Знайдіть час, щоб швидко діяти.

5. Чистий код добре справляється з одним завданням. Поганий код намагається зробити надто багато.

6. Чистий код добре протестовано.

7. При читанні добре написаного коду, кожна функція робить приблизно те, що ви очікували.

8. Якщо ви не погоджуєтесь з принципом, який викладає хтось із багаторічним досвідом, вам слід хоча б розглянути його точку зору, перш ніж ігнорувати її.

9. Код читають набагато частіше, аніж пишуть.

10. Код, що легше читати, легше змінити.

11. Залиште кодову базу у кращому вигляді, ніж коли ви її знайшли (Правило бойскауту).

Розділ 2: Значення імен

1. Ретельно вибирайте імена змінних.

2. Вибирати добрі імена складно.

3. Ім'я змінної або функції має вказувати на те, що таке і як використовується.

4. Уникайте використання односимвольних імен змінних, за винятком імен, що часто використовуються, наприклад, i для змінної лічильника в циклі.

5. Уникайте скорочення в іменах змінних.

6. Імена змінних повинні бути вимовними, щоб ви могли говорити про них і вимовляти їх уголос.

7. Використовуйте імена змінних, які можна знайти.

8. Класи та об'єкти повинні мати іменники у вигляді іменників.

9. Імена методів і функцій повинні бути дієсловами або парами дієслово-іменник.

Розділ 3: Функції

1. Функції мають бути невеликими.

2. Функція має виконувати одну дію.

3. Функції повинні мати описові імена.

4. Вийміть код у тілі if/else або переключіть оператори в чітко названі функції.

5. Обмежте кількість аргументів, які приймає функція.

6. Якщо функції потрібно багато аргументів конфігурації, розгляньте можливість об'єднання в одну змінну параметрів конфігурації.

7. Функції мають бути чистими, що означає, що вони не мають побічних ефектів та не змінюють своїх вхідних аргументів.

8. Функція повинна бути командою або запитом, але не тим і іншим одразу (Command Query Separation - Поділ запитів команд).

9. Краще видалити з коду помилки та винятки, ніж залишити помилки в коді.

10. Вийміть дубльований код у чітко названі функції (Don't Repeat Yourself).

11. Модульні тести спрощують рефакторинг.

Розділ 4: Коментарі

1. Коментарі можуть бути невірними. Вони можуть бути неправильними з самого початку або можуть бути точними, а потім з часом застаріти в міру зміни коду.

2. Використовуйте коментарі, щоб описати, чому написано так, як воно є, а не пояснювати, що відбувається.

3. Коментарів часто можна уникнути, використовуючи чітко названі змінні та витягуючи розділи коду чітко названі функції.

4. Додайте до коментарів TODO однакові префікси, щоб спростити їх пошук. Періодично переглядайте та очищуйте свої TODO-коментарі.

5. Не використовуйте Javadocs тільки для їх використання. Коментарі, що описують, що робить метод, які аргументи він приймає і що повертає, у кращому разі надмірні, а в гіршому — вводять в оману.

6. Коментарі повинні включати всю відповідну інформацію та контекст, який знадобиться читачеві. Не лінуйтеся, коли пишете коментар.

7. Коментарі журналу та коментарі автора файлу не потрібні через контроль версій та git blame.

8. Не коментуйте мертвий код. Просто видаліть його. Якщо ви думаєте, що код вам знадобиться в майбутньому, то для цього потрібний контроль версій.

Розділ 5: Форматування

1. У команді виберіть набір правил форматування коду, а потім послідовно використовуйте ці правила. Неважливо, з якими правилами ви погоджуєтесь, вам потрібно дійти згоди.

2. Використовуйте автоматичне форматування коду та аналізатор коду. Не покладайтеся на те, що люди знайдуть вручну і виправлять кожну помилку форматування. Це неефективно, непродуктивно і марнування часу під час перевірки коду.

3. Додайте вертикальні пробіли між рядками коду, щоб візуально поділити зв'язані блоки коду. Все, що вам потрібно, це зробити один новий рядок між групами.

4. Невеликі файли легше читати, розуміти та переміщати, ніж великі файли.

5. Змінні слід оголошувати поруч із тим, де вони використовуються. Для невеликих функцій це зазвичай вгорі функції.

6. Навіть для коротких функцій або операторів if все одно форматуйте їх правильно, а не записуйте в одному рядку.

Глава 6: Об'єкти та структури даних

1. Деталі реалізації в об'єкті мають бути приховані за інтерфейсом об'єкта. Надаючи інтерфейс для використання споживачами об'єкта, ви полегшує подальший рефакторинг деталей реалізації, не викликаючи критичних змін. Абстракції полегшують рефакторинг.

2. Будь-який фрагмент коду не повинен знати про внутрішній пристрій об'єкта, з яким він працює.

3. При роботі з об'єктом ви повинні вимагати від нього виконання команди або запиту, а не запитувати його про його внутрішній пристрій.

Глава 7: Виправлення помилок

1. Обробка помилок не повинна заважати решті коду в модулі.

2. Краще видалити з коду помилки та винятки, ніж залишити помилки в коді.

3. Напишіть тести з помилками, щоб переконатися, що ваш код ідентифікує їх, а чи не пропускає.

4. Повідомлення про помилки повинні бути інформативними, з усім необхідним контекстом, який може знадобитися комусь для ефективного усунення несправностей.

5. Обгортання сторонніх інтерфейсів API тонким шаром абстракції спрощує заміну однієї бібліотеки на іншу в майбутньому.

6. Обгортання сторонніх інтерфейсів API тонким шаром абстракції спрощує імітацію бібліотеки під час тестування.

7. Використовуйте шаблон Special Case або Null Object для обробки виняткової поведінки, наприклад, коли певні дані не існують.

Глава 8: Межі

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

2. Напишіть тести, щоб переконатися, що ви правильно використовуєте сторонню бібліотеку.

3. Використовуйте шаблон адаптера, щоб подолати розрив між сторонньою бібліотекою API і API, який ви хотіли б мати.

4. Обгортання сторонніх інтерфейсів API тонким шаром абстракції спрощує заміну однієї бібліотеки на іншу в майбутньому. (Повторюється з глави 7)

5. Обгортання сторонніх інтерфейсів API тонким шаром абстракції спрощує імітацію бібліотеки під час тестування. (Повторюється з глави 7)

6. Намагайтеся не повідомляти вашому додатку занадто багато інформації про деталі будь-якої сторонньої бібліотеки.

7. Краще залежати від того, що ви контролюєте, ніж від того, що ви не контролюєте.

Розділ 9: Модульні тести

1. Тестовий код повинен бути таким самим чистим, як і виробничий код (за деякими винятками, зазвичай пов'язаними з пам'яттю або ефективністю).

2. У міру зміни коду виробництва змінюється і тестовий код.

3. Тести допомагають зберегти ваш виробничий код гнучким та підтримуваним.

4. Тести дозволяють вносити зміни, дозволяючи вам впевнено виконувати рефакторинг, не побоюючись, що ви цього не помітите.

5. Структуруйте свої тести за допомогою шаблону Arrange-Act-Assert (також відомого як Build-Operate-Check, Setup-Exercise-Verify або Given-When-Then).

6. Використовуйте функції, що залежать від предметної області, щоб спростити написання та читання тестів.

7. Оцініть одну концепцію тесту.

8. Тести мають бути швидкими.

9. Тести мають бути незалежними.

10. Тести мають бути повторюваними.

11. Тести не мають вимагати підтверджень.

12. Тести мають бути написані вчасно, незадовго до чи після написання виробничого коду, а чи не за кілька місяців.

13. Якщо ваші тести будуть неправильними, очікуйте, що у вашому коді будуть помилки.

Розділ 10: Класи

1. Класи мають бути невеликими.

2. Класи повинні відповідати лише за одну річ і повинні мати лише одну причину зміни (принцип єдиної відповідальності).

3. Якщо ви не можете вигадати чітку назву для класу, ймовірно, він занадто великий.

4. Ваша робота не закінчується на тому, що ви змусите частину коду працювати. Наступним кроком стане рефакторинг та очищення коду.

5. Використання безлічі невеликих класів замість кількох великих класів у вашому додатку скорочує обсяг інформації, яку розробник повинен розуміти під час роботи над заданим завданням.

6. Наявність гарного набору тестів дозволяє з упевненістю виконувати рефакторинг, коли ви розбиваєте великі класи на дрібніші.

7. Класи мають бути відкриті для розширення, але закриті для модифікації (принцип відкритості-закритості).

8. Інтерфейси та абстрактні класи створюють стики (seams), які спрощують тестування.

Глава 11: Системи

1. Використовуйте впровадження залежностей, щоб розробникам надати гнучкість для передачі будь-якого об'єкта з відповідним інтерфейсом в інший клас.

2. Використовуйте впровадження залежностей для створення стиків об'єктів у програмі, щоб спростити тестування.

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

4. Відкладіть ухвалення рішення до останнього відповідального моменту.

5. Використовуйте предметно-орієнтовану мову, щоб експерти та розробники в предметній галузі використовували ту саму термінологію.

6. Не ускладнюйте свою систему надто сильно. Використовуйте найпростіше, що працює.

Розділ 12: Розгортання

1. Системи, які не можна тестувати, не можна перевірити, а системи, які не можна перевірити, ніколи не слід розгортати.

2. Написання тестів призводить до кращого дизайну, тому що код, який легко тестувати, часто використовує впровадження залежностей, інтерфейсів та абстракцій.

3. Хороший набір тестів позбавить вас від страху зламати програму під час рефакторингу.

4. Дублювання коду створює більший ризик, оскільки код має більше місць, які можна змінити, і ще більше місць, де помилки можуть бути приховані.

5. Код, який ви пишете зараз, легше зрозуміти, тому що ви глибоко залучені до його розуміння. Іншим непросто швидко досягти такого рівня розуміння.

6. Більшість вартості програмного проекту пов'язані з довгостроковим обслуговуванням.

7. Тести служать живою документацією того, як ваш додаток повинен (і поводиться) поводитися.

8. Не рухайтеся далі, коли ваш код запрацює. Знайдіть час, щоб зробити його більш зрозумілим та зрозумілим.

9. Наступним, хто прочитає ваш код у найближчому майбутньому, швидше за все, ви будете. Будьте ласкаві до себе в майбутньому, написавши простий для розуміння код.

10. Опирайтеся догмам. Прийміть прагматизм.

11. Щоб стати справді добрим фахівцем у галузі розробки програмного забезпечення, потрібні десятиліття. Ви можете прискорити процес навчання, вивчаючи досвід навколишніх експертів і вивчаючи шаблони проектування, що часто використовуються.

Глава 13: Паралелізм

1. Писати паралельний код складно.

2. Випадкові помилки та проблеми, які важко відтворити, часто є проблемами паралелізму.

3. Тестування не гарантує відсутність помилок у вашій програмі, але мінімізує ризик.

4. Дізнайтеся про загальні проблеми паралелізму та їх можливі рішення.

Глава 14: Послідовне уточнення

1. Чистий код зазвичай не починається з чистого аркуша. Спочатку ви пишете чорнове рішення, а потім реорганізуєте його, щоб зробити його чистішим.

2. Помилково припиняти роботу над кодом, коли він “заробив”. Знайдіть час, щоб зробити його ще краще після того, як він працює.

3. Заворушення наростають поступово.

4. Якщо ви опинабося у скрутному становищі, коли додавання функцій надто складне або займає занадто багато часу, припиніть писати функції та почніть рефакторинг.

5. Поступові зміни часто кращі, ніж відновлення з нуля.

6. Використовуйте розробку через тестування (Test-Driven Development — TDD), щоб зробити велику кількість дуже дрібних змін.

7. Хороший дизайн програмного забезпечення передбачає поділ проблем у вашому коді та поділ коду на дрібніші модулі, класи та файли.

8. Легше прибрати безлад відразу після того, як ви його створабо, ніж прибирати пізніше.

Розділ 15: Внутрішній пристрій JUnit

1. Негативні імена змінних чи умовні висловлювання трохи важче зрозуміти, ніж позитивні.

2. Рефакторинг - це ітеративний процес, повний спроб і помилок.

3. Залиште кодову базу у кращому вигляді, ніж коли ви її знайшли (Правило бойскауту). (Повторюється з глави 1)

Глава 16: Рефакторинг SerialDate

1. Перевірки коду та критика нашого коду роблять нас кращими, і ми повинні вітати це.

2. Спершу змусіть код працювати, потім виправте.

3. Не кожен рядок коду потрібне тестування.

Глава 17: Запахи та евристика

1. Чистий код – це не набір правил, а скоріше система цінностей, що визначають якість вашої роботи.

[У цьому розділі дядько Боб перераховує ще 66 варіантів свого коду і евристик, багато з яких були розглянуті в частині книги, що залишилася. Відтворення їх тут, насправді, було б копіюванням і вставкою назви кожного елемента, тому я утримався від цього. Натомість я б порадив вам прочитати книгу!]

Висновок

Давайте закінчимо з того, з чого почали: "Чистий код" Роберта К. Мартіна - книга, яка рекомендується з програмування всіх часів. На те є вагома причина.