12-Good-Programming-Style

12-Good-Programming-Style - CS106X Winter 2008 Handout 12...

Info iconThis preview shows pages 1–3. Sign up to view the full content.

View Full Document Right Arrow Icon
CS106X Handout 12 Winter 2008 January 18, 2008 Good Programming Style Thanks to Julie Zelenski, Nick Parlante, and Bob Plummer for this handout. As we will stress all quarter, a working program is only half the challenge—constructing an elegant and well-engineered solution is your ultimate goal. Developing a good sense of style takes practice and work, conveniently we've got plenty of both coming up in 106X! Your section leader's feedback on your code will be invaluable in helping you learn how to design and organize code in a clear, readable manner that works for you. As with any complex activity, there is no one "right" way that can easily described, nor is there an easy-to-follow checklist of do's and don'ts. But that said, this handout will try to identify some qualities that can contribute to readable, maintainable programs to give you an idea what we're working towards. Commenting The motivation for commenting comes from the fact that a program is read many more times that it is written. A program must strive to be readable, and not just to the programmer who wrote it. A program expresses an algorithm to the computer. A program is clear or "readable" if it also does a good job of communicating the algorithm to a human. Given that C++ is a rather cryptic means of communication, an English description is often needed to understand what a program is trying to accomplish or how it was designed. Comments can provide information that is difficult or get from reading the code. Some examples of information you might find in comments: General overview. What are the goals and requirements of this program? This function? Data structures. How is data is stored? How is it ordered, searched, accessed? Design decisions. Why was a particular data structure or algorithm chosen? Were other strategies were tried and rejected? Error handling. How are error conditions handled? What assumptions are made? What happens if those assumptions are violated? Coding details. Comments are invaluable for explaining the inner workings of particularly complicated (often labeled "clever") paths of the code. Planning for future. How might one make modifications or extensions later? And much more. .. (This list is by no means exhaustive) At the top of each file, it is a good convention to begin with an overview comment for the program, interface, or implementation contained in the file. The overview is the single most important comment in a program. It's the first thing that anyone examining your code will read. The overview comment explains, in general terms, what strategy the program uses to produce its output. The program header should lay out a roadmap
Background image of page 1

Info iconThis preview has intentionally blurred sections. Sign up to view the full version.

View Full DocumentRight Arrow Icon
of how the algorithm works—pointing out the important routines and discussing the data structures. The overview should mention the role of any other files or modules that the program depends on. Essentially, the overview contains all the information which is not specific or low-level enough to be in a function comment, but which is helpful for understanding the program as a whole.
Background image of page 2
Image of page 3
This is the end of the preview. Sign up to access the rest of the document.

This note was uploaded on 04/18/2008 for the course CS 106X taught by Professor Cain,g during the Winter '08 term at Stanford.

Page1 / 6

12-Good-Programming-Style - CS106X Winter 2008 Handout 12...

This preview shows document pages 1 - 3. Sign up to view the full document.

View Full Document Right Arrow Icon
Ask a homework question - tutors are online