Professional C__ - Marc Gregoire [61]
This chapter presented three specific tips for structuring your code: Avoid combining unrelated or logically separate concepts, use templates for generic data structures and algorithms, and provide appropriate checks and safeguards.
The chapter also presented six strategies for designing interfaces: Develop easy-to-use interfaces, don’t omit required functionality, present uncluttered interfaces, provide documentation and comments, provide multiple ways to perform the same functionality, and provide customizability. It concluded with two tips for reconciling the often-conflicting demands of generality and ease of use: Supply multiple interfaces and make common functionality easy to use.
The next (and last) chapter of Part I discusses coding style, which is important especially when working on a project with many people.
Chapter 5
Coding with Style
WHAT’S IN THIS CHAPTER?
The importance of documenting your code, and what kind of commenting styles you can use
What decomposition means and how to use it
What naming conventions are
What formatting rules are
If you’re going to spend several hours each day in front of a keyboard writing code, you should take some pride in all that work. Writing code that gets the job done is only part of a programmer’s work. After all, anybody can learn the fundamentals of coding. It takes a true master to code with style.
This chapter explores the question of what makes good code. Along the way, you’ll see several approaches to C++ style. As you will discover, simply changing the style of code can make it appear very different. For example, C++ code written by Windows programmers often has its own style, using Windows conventions. It almost looks like a completely different language than C++ code written by Mac OS programmers. Exposure to several different styles will help you avoid that sinking feeling you get when opening up a C++ source file that barely resembles the C++ you thought you knew.
THE IMPORTANCE OF LOOKING GOOD
Writing code that is stylistically “good” takes time. You could probably whip together a program to parse an XML file in a couple of hours. Writing the same program with functional decomposition, adequate comments, and a clean structure would probably take days. Is it really worth it?
Thinking Ahead
How confident would you be in your code if a new programmer had to work with it a year from now? One of the authors, faced with a growing mess of web application code, encouraged his team to think about a hypothetical intern who would be starting in a year. How would this poor intern ever get up to speed on the code base when there was no documentation and scary multiple-page functions? When you’re writing code, imagine that somebody new will have to maintain it in the future. Will you even remember how it works? What if you’re not available to help? Well-written code avoids these problems because it is easy to read and understand.
Elements of Good Style
It is difficult to enumerate the characteristics of code that make it “stylistically good.” Over time, you’ll find styles that you like and notice useful techniques in code that others wrote. Perhaps more important, you’ll encounter horrible code that teaches you what to avoid. However, good code shares several universal tenets that will be explored in this chapter.
Documentation
Decomposition
Naming
Use of the Language
Formatting
DOCUMENTING YOUR CODE
In the programming context, documentation usually refers to comments contained in the source files. Comments are your opportunity to tell the world what was going through your head when you wrote the accompanying code. They are a place to say anything that isn’t obvious from looking at the code itself.
Reasons to Write Comments
It may seem obvious that writing comments is a good idea, but have