office source code style guide
dave parker, 6/30/95
abstract
this document outlines a general style guide for c and c++ source code in office development. the main purpose here is to list features of c++ which we will use and which we will avoid, along with the basic rationale for doing so. there are also standards for basic coding issues for the sake of consistency within the code and robust constructs. this is not a complete list of c/c++ language features with commentary. rather, it mentions only the issues we consider important. knowledge of c++ is assumed.
contents
1. general goals 3
2. classes 3
2.1 class vs. struct 4
2.2 public, private, and protected members 4
2.3 data members 4
2.4 virtual functions 5
2.5 constructors 5
2.6 destructors 6
2.7 new and delete 7
2.8 operators 7
2.9 inheritance 8
2.9.1 inheritance of interface vs. implementation 8
2.9.2 inheritance vs. containment 10
2.9.3 multiple inheritance 11
3. other c++ features 11
3.1 constants and enumerations 12
3.2 references 12
3.3 const parameters and functions 13
3.4 default arguments 13
3.5 function overloading 14
3.6 operator overloading 14
4. common c/c++ issues 14
4.1 #ifdefs 14
4.2 global variables 15
4.3 macros and inline functions 16
4.4 optimization 16
4.5 warnings 17
4.6 private data and functions 17
4.7 typedefs 17
4.8 basic data types 17
4.9 pointers 18
4.10 switch statements 19
4.11 asserts 19
4.12 errors and exceptions 19
5. formatting conventions 20
5.1 naming conventions 20
5.2 function prototypes 21
5.3 variable declarations 22
5.4 class declarations 22
5.5 comments 23
5.5.1 file headers and section separators 23
5.5.2 function headers 24
5.5.3 in-code comments 25
5.5.4 attention markers 25
5.6 misc. formatting conventions 26
5.7 source file organization 27
5.7.1 public interface files 27
5.7.2 private interface files 28
5.7.3 implementation files 28
5.7.4 base filenames 29
6. interfaces to dlls 29
6.1 c functions and global variables 29
6.2 common c/c++ public header files 29
6.3 lightweight com objects and isimpleunknown 30
7. appendix a: basic hungarian reference 33
7.1 making hungarian names 33
7.2 standard base tags 33
7.3 standard prefixes 34
7.4 standard qualifiers 35
1. general goals
c++ is a complex language that provides many ways to do things, and going 搘hole hog” on all of its features can lead to confusion, inefficiency, or maintenance problems. all office developers need to become experts on the features we will use, and avoid the others in order to form solid conventions within the group that we are all comfortable with. our use of c++ features will be fairly conservative. we抎 much rather err on the side of just dealing with c, which we抮e all used to, then screwing up our app with a new concept that not all of us are used to.
underlying the choice of all of the style decisions are a few basic goals, as listed below. when in doubt about a particular issue, always think about the spirit of these goals. sometimes these goals will conflict, of course, and in these cases we try to either prioritize the tradeoffs or use experience (either our own or from other groups that have used c++ extensively).
1. simplicity. when in doubt, keep it simple. bugs are related mostly to complexity, not code.
2. clarity. the code should do what it looks like it抯 doing. other people need to be able to understand your code.
3. efficiency. speed and size are important. using c++ does not imply big and slow. there are plenty of perfectly reasonable ways to make things as fast or faster than the normal c way. speed and size often trade off, and most people probably err on the side of choosing speed too often. remember that 20% of the code is responsible for 80% of the time. in most cases, we抮e more concerned about fitting comfortably in less ram.
4. appropriateness. use the language construct that is appropriate for the abstraction or operation you are trying to do. do not abuse the language. don抰 use a construct just because it happens to work. definitely don抰 use a strange construct to amaze and confuse your friends to try to show how smart you are.
