Clean code: Qualidade e excelência no código (Published)
The world demands better code. - "Uncle Bob", Robert C. Martin
What is "Clean Code"?
Clean Code is a set of best practices for writing code that is clean, easy to understand, maintain, and evolve.
Principles:
- Naming conventions
- Small and simple functions (SOLID principles)
- Precise and useful comments
- Reusability
- Testing
- Standardization
- Separation of responsibilities
- Reduction of complexity (KISS)
- Constant refactoring (scout rule)
- Code formatting (elegance)
"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." - Martin Fowler
"Can I see your code?"
"It's still messy; I'll improve and refactor the code later."
Ugly children have no parents! 😂
"I did my best within the time I had." "But the deadline was extremely short." "My manager pressures me all the time." "I need to deliver, I need to be very productive."
When we hear these phrases, it's certain that the professional isn't satisfied with the work done and isn't proud of their own code. The code is likely poorly structured and challenging to maintain. Often, when other developers analyze such contaminated code, they prefer starting a new project from scratch instead of venturing into that code.
There's no excuse for poorly written code!
Take pride in your code.
Enough small talk; let's get to the point.
Examples? We have them!
1. Naming
- Use descriptive names: choose names that clearly describe the purpose or function of the variable, method, or class, regardless of length.
- Avoid generic names: names like "data," "temp," "aux," "var," among others, are uninformative and can cause confusion.
- Use pronounceable names: names that are easy to pronounce are easier to remember and understand.
- Avoid abbreviations: abbreviations can be confusing and hard to understand, especially for new team members.
- Booleans should start with “is,” “has,” or “have”: e.g., isMobile
- Maintain consistency: always!
Bad code example:
Clean code example:
2. Classes
- Use descriptive names: choose names that clearly describe the purpose or function of the variable, method, or class, regardless of length.
- Represent with nouns: helps create a direct association between the class and the entity it represents, making the code more readable and understandable.
- Clear name in its context: helps understand its function and relation with other classes, avoiding confusions and errors.
- Maintain consistency: always!
Bad code example:
Clean code example:
3. Methods
- Use descriptive names: choose names that clearly describe the purpose or function of the variable, method, or class, regardless of length.
- Use verbs for methods: methods should be named with verbs that clearly describe what they do.
- Keep them small: the smaller, the better.
- Extract whenever possible into helper methods: private or utility methods.
- Single responsibility: a method should do only one thing, one.
- Many parameters should be replaced by objects: data transfer object (DTO).
- Maintain consistency: always!
Bad code example:
Clean code example:
4. Conditions
- Use descriptive names: choose names that clearly describe the purpose or function of the variable, method, or class, regardless of length.
- Extract to private methods whenever possible.
- Methods returning booleans should start with “is,” “has,” or “have”: e.g., isValidNumber
- Avoid negatively written methods: e.g., isNotValid
- Avoid inline if-else: makes the code less readable and inconsistent.
- Maintain consistency: always!
Bad code example:
Clean code example:
5. Abstraction
- Use descriptive names: choose names that clearly describe the purpose or function of the variable, method, or class, regardless of length.
- Try to generalize your classes as much as possible: whenever possible.
- Abstract as many levels as necessary: don't be afraid.
- Maintain consistency: always!
Bad code example:
Clean code example:
6. Exceptions
- Use specific exceptions for your errors: it's easier to test and maintain.
- Avoid error codes: e.g., 1103, 1104, 1201.
- Handle exceptions exclusively in methods: no matter how long the treatment is.
- Maintain consistency: always!
Bad code example:
Clean code example:
7. Law of Demeter
A method M of a class C should only know:
- Methods of C
- Global objects of the application
- Objects in properties of instances of C
- Objects passed as parameters to M
- Objects created by M
Bad code example:
Clean code example:
8. Comments
- Well-written code eliminates the need for excessive comments.
- Acceptable when there's a need to explain business rules, especially specific ones.
- Licensing and documentation information should be clear.
- Maintain consistency: always!
Bad code example:
Clean code example:
9. Code Formatting (Elegance)
- There's no definitive standard for code formatting.
- Define rules within the team.
- Always opt for the community-adopted standard, even if it makes the code longer.
- Maintain spacing between blocks for better readability.
- Maintain consistency: always!
Bad code example:
Clean code example:
10. Testing
- TDD (Test-Driven Development) is preferable; if not, implement tests continuously with each change.
- Use and create various types of tests: integration, functional, unit tests, etc.
- Maintain consistency: always!
Follow the "F.I.R.S.T." principles for testing:
- Fast: Tests should provide quick results.
- Independent: Tests should not have dependencies on each other.
- Repeatable: Tests should work consistently in any environment.
- Self-validation: No manual validation should be required.
- Timely: Tests should be written before the code.
Scout Rule (Rule of the Scout)
"Leave the campground cleaner than you found it." "Leave the code cleaner than you found it."
That's it!
Developing projects with quality is challenging, especially with tight deadlines, but by adhering to standards and best practices, you can increase the chances of success.
Take pride in your code and show that you care. Poor code can harm careers and destroy companies.
I hope your coding performance improves after this presentation. Let's work together to make the world a better place for us developers.
And don't forget, always maintain the standard and take pride in your code!