CS 215 – Fundamentals of Programming IIC++ Programming Style GuidelineMost of a programmer's efforts are aimed at the development of correct and efficient programs. But the readability of programs is also important. There are many ``standards'' in use. Since following them will not guarantee good code, these ``standards'' are actually guidelines of style. Each one has its proponents and detractors. The textbook advocates one particular style for C++ programs. This document collects the style comments in the textbook into one place and adds some documentation requirements for this course. The essential point is that a program is a medium of communication between humans; a clear, consistent style will make it that much easier for you to communicate. Program Documentation Since this course does not require a separate analysis and design document, much of what would have been in such a document is required to appear in the comments of your program files. Makefiles Makefiles should begin with a comment section of the following form and with the following information filled in: # File: <name of file># Class: CS 215 Instructor: Dr. Deborah Hwang# Assignment: Date assigned: # Programmer: Date completed:Main Program Heading The main program file should begin with a comment section of the following form and with the following information filled in: // File: <name of file>// < Description of what the program does >//// Input: < Description of data that the program asks the user for// or reads from a file >// Output: < Description of what the program outputs as a result // either to the screen or to a file >// ------------------------------------------------------------------// Class: CS 215 Instructor: Dr. Deborah Hwang// Assignment: Date assigned: // Programmer: Date completed:Class File Headings Class definitions and implementations should be divided into multiple files so that we can reuse them easily. By convention, the class definition and related free functions prototypes are stored in a header file which has the extension ".h". The implementations of the class member, friend, and overloaded operator functions are stored in a source file with the extension ".cpp". The main program is usually stored in a separate source file that includes the header files for each class used. Every class header file should use compiler directives #ifndef, #define, and #endif to ensure a header file is only included once. The symbol should be the name of the header file in all capital letters with an underscore (_) replacing the dot and a trailing underscore. For example, for the header file counter.h, the directives would be: #ifndef COUNTER_H_#define COUNTER_H_08/27/07 1 of 7class Counter{ ...}; // end Counter#endif // COUNTER_H_Every class header file should start with a comment block with the following information filled in: // File: <name of file>// Header file for <class>// < Description of what the class represents >// // Class: CS 215 Instructor: Dr. Deborah Hwang// Assignment: Date assigned: // Programmer: Date completed:Every class source file should start with a comment block with the following information filled in: // File: <name of file>// Implementation file for <class>//// Class: CS 215 Instructor: Dr. Deborah Hwang// Assignment: Date assigned: // Programmer: Date completed:Preprocessor Section In the preprocessor section, include statements for header files should have comments indicating the types, constants, variables, or functions used from the header. For example, #include <iostream> // cin, cout, <<, >>, endl#include <cmath> // sin, cos#include "list.h" // List classClass Definitions The qualifiers public and private should be indented and the member and friend function prototypes and data member declarations indented in from the qualifiers. Free function prototypes should appear after the class definition. For example, class Counter{ public: // Constructors Counter (); // Creates counter with value of 0 // Accessors int Value () const; // Returns the current value of the counter // Friend functions friend operator++(); // Increments counter by 1 ... private: int value; // Current value of the counter}; // end Counter08/27/07 2 of 7// Free overloaded I/O operatorsistream& operator>> (istream& in, Counter& theCounter);ostream& operator<< (ostream& out, const Counter& theCounter);Member and friend function prototypes should appear in the same order as presented in the class specification. If there are many member functions, comments indicating grouping are helpful. E.g., constructors, accessors, mutators, I/O, etc. Short comments describing what member functions do and what member data represent should be included as shown above. Member functions that do not change the state of the object should be declared as const as shown above for the Value member function. Class member, friend, and overloaded function implementations should appear in the same order as presented in the class definition. Function Headings Include documentation, as needed, of the following form for each function: // Function: <name of function>// Returns: <returned object, if any>//// < Short description of what function does in terms of the // received parameters >// < Assumptions about the state or values of the received // parameters >void Sample (type1 arg1, // REC'D: <short description of object> type2& arg2,...) // P'BACK: <short description of object>{ ...} // end SampleThere should be one formal parameter per line, lined up under each other as shown above with comments about the movement and description of the parameter. The movement of a parameter is in relation to the function and refers to whether the data is received from the caller or passed back to the caller. Function comment headers should be included with member function definitions also. If there are many function definitions, comments indicating grouping are helpful. (E.g., accessors, mutators, I/O, etc.) Identifiers and Commenting Identifiers should be chosen to be self-documenting. Abbreviations, except where standard, should be avoided. In addition,
View Full Document
Unlocking...