As software developers, we can write a lot of code each day. Each piece of code has its own story. It could be:
- Inspired by a web resource (forum, tutorial, blog post, etc.).
- Inspired by an open-source project from GitHub, SourceForge, or elsewhere.
- Copied and pasted from the project itself.
- Developed from scratch.
For each piece of code, the developer analyzes the problem to be solved. Their background and the opinions of their team can greatly influence their choices and the way the code is written.
After writing and committing code, keep in mind that it may introduce technical debt that the project maintainers and developers will have to address sooner or later. To minimize this debt and make the task easier for everyone working on the project, it is best to adopt a few good habits that keep the code clean from the start.
1. Naming
Sometimes we spend a lot of time just trying to understand the purpose of a variable or a function because it’s named a, b or x. If it had been given a clear, meaningful name from the beginning, its meaning would be obvious.
Clear, meaningful names that follow a consistent naming convention help:
- Reduce the effort required to read and understand the source code;
- Allow code reviews to focus on more important issues rather than debates over syntax and naming conventions.
- Allow code-quality tools to focus their reports on significant issues rather than syntax and style preferences.
2. Visibility
Narrowing visibility is a good practice because it promotes encapsulation. Keeping scope to a minimum helps users of your code understand exactly which members are intended to be accessed from outside a class.
Making all class methods public can confuse users and obscure the class contract; in that case, documentation is needed to determine which methods are intended to be used.
3. Parameters
A function that takes more than five parameters indicates one of two problems:
- The function is doing too much. It should be split into several smaller functions, each with a smaller parameter set.
- There is another object hiding in there. You may need to create another object or data structure that includes these parameters.
Doing this provides several benefits:
- It makes your code easier to read.
- It makes unit testing easier.
4. Size
Overly long methods are not easy to maintain and understand. Here’s some advice about the length of functions from the Linux coding style web page:
Functions should be short and sweet, and do just one thing. They should
fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
as we all know), and do one thing and do that well.
The maximum length of a function is inversely proportional to the
complexity and indentation level of that function. So, if you have a
conceptually simple function that is just one long (but simple)
case-statement, where you have to do lots of small things for a lot of
different cases, it's OK to have a longer function.
5. Number of local variables
Methods where NbVariables is greater than 8 are difficult to understand and maintain. Methods where NbVariables is greater than 15 are extremely complex and should be split into smaller methods (unless they are automatically generated by a tool).
6. Avoid defining complex functions
Many metrics can be used to detect complex functions; NBLinesOfCode, the number of parameters, and the number of local variables are the most basic ones.
Other useful metrics can help identify complex functions:
- Cyclomatic complexity is a popular procedural software metric whose result is equal to the number of decisions that can be taken in a procedure.
- Nesting Depth is a method-level metric that represents the maximum depth of nested scopes within a method body.
- Max Nested Loops is equal to the maximum level of loop nesting in a function.
The maximum acceptable values for these metrics depend largely on the team’s preferences, as there are no universal thresholds.
Let’s look for functions that may need refactoring:
7. Formatting
Programming style and indentation can be defined as the way you choose to organize and document your source code. Code indentation is part of programming style and is largely about readability and aesthetics. If we follow a proper style guide and indentation, a program can be just like a POEM, and the reader will be comfortable enough to SAIL through it and understand its meaning. As we know, proper code indentation makes it:
- Easier to read
- Easier to understand
- Easier to modify
- Easier to maintain
- Easier to enhance
The purpose of code indentation and style is to make a program easier to read and understand. This saves a great deal of time when we revisit or reuse the code. A style guide provides a road map that the developer should follow when coding, so that in a group of developers, all the code produced is consistent in nature and reusable by any developer.
8. Comments
Sometimes code has no comments at all, while in other cases it is over-commented. Maybe you’ve already read this phrase: Good code is self-documenting.
Yes, it’s good practice to keep the code clean and let it speak for itself, avoiding comments — but in the real world that’s not always easy. In some cases, you need to clarify what the code does.
9. Coupling
Low coupling is desirable because a change in one area of an application will require fewer changes elsewhere in the application. In the long run, this can reduce the time, effort, and cost associated with modifying an application and adding new features.
Functions that depend on many other functions can be difficult to understand and maintain. It’s recommended to minimize the efferent coupling of your functions.
10. Cohesion
The single responsibility principle states that a class should not have more than one reason to change. Such a class is said to be cohesive. A high LCOM value generally pinpoints a poorly cohesive class. There are several LCOM metrics. LCOM takes its values in the range [0-1]. LCOM HS (HS stands for Henderson-Sellers) takes its values in the range [0-2]. An LCOM HS value higher than 1 should be considered alarming. Here is how to compute the LCOM metrics:
LCOM = 1 – (sum(MF)/M*F) LCOM HS = (M – sum(MF)/F)(M-1)
Where:
- M is the number of methods in the class (both static and instance methods are counted; it also includes constructors, property getters/setters, and event add/remove methods).
- F is the number of instance fields in the class.
- MF is the number of methods of the class accessing a particular instance field.
- Sum(MF) is the sum of MF over all instance fields of the class.
The underlying idea behind these formulas can be stated as follows: a class is utterly cohesive if all its methods use all its instance fields, which means that sum(MF)=M*F, and then LCOM = 0 and LCOMHS = 0.
LCOMHS value higher than 1 should be considered alarming.
Conclusion
These are a few basic habits that can help keep your code clean from the beginning. Don’t wait for a major refactoring to clean it up—try to keep it clean from the start.