next up previous
Next: About this document ... Up: C++ Programming Style Previous: Documentation

Conclusion

We have looked at a great many examples, and we have seen some general rules, but our work has really only begun. We have started to try to think about code from the point of view of our reader, the person we are really trying to communicate with, rather than thinking about the compiler. But writing is hard, and rules change over time. For example, there was a time when I would be castigated for starting the sentence before this with ``but,'' because ``but'' is a coordinating conjunction, and there is no clause that I was coordinating with. Fortunately, that rule is less enforced nowadays, and I felt I had a good rhetorical reason for breaking it. In other words, I was willing to break a rule in order to strive for better communication. The rules serve us, not vice versa.

Because writing is hard, even though you've had many years of practice, you should expect that proper programming style is difficult, too. Indentation, braces, and simple stuff like that you'll pick up quickly. What takes years of practice--and we're all still learning--is trying to anticipate what the reader will and won't understand, and describing the code in ways that make it clear and accessible. Even choosing good names for variables and functions is cause for thought and consideration. If you start feeling sorry for yourself, remember that Compared to writing a good essay, documentation is easy.

Work at it, practice, and, if you're in doubt, ask your professor. We don't all have the same style, and our answers won't necessarily agree, but we do have more experience and we'll do our best to help. Becoming a good programmer includes good documentation, because even the most brilliant code becomes obsolete if no one can understand it. Finally, even if it's not your life's ambition to be a great programmer, learning to express your ideas clearly in English is important.


next up previous
Next: About this document ... Up: C++ Programming Style Previous: Documentation
James Hale
2001-09-19