Professional C__ - Marc Gregoire [66]
Good code is naturally readable and only requires comments to provide useful additional information.
Comments in This Book
The code examples you will see in this book often use comments to explain complicated code or to point things out to you that may not be evident. We usually omit any prefix comments and fixed-format comments to save space, but we wholeheartedly advocate their inclusion in professional C++ projects.
DECOMPOSITION
Decomposition is the practice of breaking up code into smaller pieces. There is nothing more daunting in the world of coding than opening up a file of source code to find 300-line functions and massive nested blocks of code. Ideally, each function or method should accomplish a single task. Any subtasks of significant complexity should be decomposed into separate functions or methods. For example, if somebody asks you what a method does and you answer “First it does A, then it does B; then, if C, it does D; otherwise, it does E,” you should probably have separate helper methods for A, B, C, D, and E.
Decomposition is not an exact science. Some programmers will say that no function should be longer than a page of printed code. That may be a good rule of thumb, but you could certainly find a quarter-page of code that is desperately in need of decomposition. Another rule of thumb is whether the code is long or short, if you squint your eyes and look at the format of the code without reading the actual content, it shouldn’t appear too dense in any one area. For example, Figures 5-2 and 5-3 show code that has been purposely blurred so that you can’t read the content. It should be obvious that the code in Figure 5-3 has better decomposition than the code in Figure 5-2.
FIGURE 5-2
FIGURE 5-3
Decomposition through Refactoring
Sometimes when you’ve had a few coffees and you’re really in the programming zone, you start coding so fast that you end up with code that does exactly what it’s supposed to do, but is far from pretty. All programmers do this from time to time. Short periods of vigorous coding are sometimes the most productive times in the course of a project. Dense code also arises over the course of time as code is modified. As new requirements and bug fixes emerge, existing code is amended with small modifications. The computing term cruft refers to the gradual accumulation of small amounts of code that eventually turns a once-elegant piece of code into a mess of patches and special cases.
Refactoring is the act of restructuring your code. The following are a couple of example techniques that you can use to refactor your code. Consult a refactoring book listed in Appendix B to get a more comprehensive list.
Techniques that allow for more abstraction: Encapsulate Field: Make a field protected and give access to it with getter and setter methods.
Generalize Type: Create more general types to allow for more code sharing.
Techniques for breaking code apart into more logical pieces: Extract Method: Turn part of a larger method into a new method to make it easier to understand.
Extract Class: Move part of the code from an existing class into a new class.
Techniques for improving names and the location of code: Move Method or Move Field: Move to a more appropriate class or source file.
Rename Method or Rename Field: Change the name to better reveal its purpose.
Pull Up: In OOP, move to a superclass.
Push Down: In OOP, move to a subclass.
Whether your code starts its life as a dense block of unreadable cruft or it just evolves that way, refactoring is necessary to periodically purge the code of accumulated hacks. Through refactoring, you revisit existing code and rewrite it to make it more readable and maintainable. Refactoring is an opportunity to revisit the decomposition of code. If the purpose of the code has changed or if it was never decomposed in the first place, when you refactor the code, squint at it and determine if it needs to be broken down into smaller parts.
Decomposition by Design
If you use modular decomposition