1、STANDARD DEVELOPMENT AND CODING PRACTICES AT MSRA Compiled by Advanced Technology Department M I C R O S O F T R E S E A R C H A S I A Ver. 0.1 January 21, 2002 Content CONTENT.1 A DAY IN THE LIFE OF A RESEARCH DEVELOPER.1 INTRODUCTION.1 WHAT SHOULD I DO EACH DAY?.1 YOUR MACHINE ENVIRONMENT.2 KNOW Y

2、OUR RESOURCES.2 REQUIRED READING LIST.2 OTHER RECOMMENDED READING.2 MODIFICATION HISTORY.2 CODING STYLE GUIDELINES.3 INTRODUCTION.3 NAMING CONVENTIONS.3 CODE FORMATTING.4 IMPLEMENTATION ISSUES.9 CODING STYLE CHECKLIST .11 1CLASSES.11 2OTHER C/C+ ISSUES.11 3SOURCE FILE ORGANIZATION.11 4BASIC DATA TYP

3、ES.11 5NAMING CONVENTIONS.11 6FORMATTING ISSUES.11 SOURCEDEPOT, NT BUILD AND RAID.12 1SOURCEDEPOT.12 2NT BUILD SYSTEM.12 3RAID SYSTEM.12 A Day in the Life of a Research Developer Introduction Welcome to MSRA development, also known as the RSDE (research software design engineer) and AT (advanced tec

4、hnology) team. This purpose of this document is to give the new research developer at MSRA a leg-up in understanding the tools and resources available in accomplishing his or her daily duties and responsibilities, and is modeled after the Day in the Life of an Office Developer document. What Should

5、I Do Each Day? At Microsoft, the most important application to track is Outlook. This is because much communication is tracked through e-mail and scheduling. (Tip: If you find yourself distracted by too many e-mails, use Inbox Assistant to sift and prioritize. Choose specific times during the day to

6、 check e-mail.) People will generally expect you to read and reply to e-mail within the same day it is sent. Microsofts Product Cycle Model is geared towards product teams with traditional client applications, but it is still important to familiarize yourself with this. Within the context of this, y

7、ou should have the following specific tasks to work on: Coding: Coding is the most important task you take on as developer. They are many ways to code. However, there is only one way to code it right. Thats why each group has a coding style guideline to follow. The goal of such document is to ensure

8、 everyone in the organization code in a similar fashion, so that all codes written by different developers can be easily understood and maintained. This is extremely important for project development. This document, “Coding Style Guidelines”, outlines the most common guidelines we use as developer a

9、t MSRA. We highly recommend everyone, if you write code, follow these guidelines. Source code Check-in/Backup and Build: As coding is the most important task for each developer, source code management is even more important. The only way to make sure you dont lose your hard work is to backup your co

10、de everyday. On top of that, if more than one developer or researcher is working on the same project, most likely they will need to share code. The most efficient way to do that is to use source code management software. The most commonly used source code management software at Microsoft is Source D

11、epot. With the widely used NT build environment, you can compile and build any code you write with a simple command line command. Please see “Source Depot and NT build environment” for more details. Code review and Design Review: After finish coding, the most common practice for developer is to do c

12、ode review. One of the purposes of code review is to get a second opinion on how certain codes should be written and detect if there is any code defect. But the main purpose of code review is to allow developer himself to go through his own code and detect code defect before check-in. Code review is

13、 normally held within a small group of developers and researchers. Everyone should be allowed to give feedback. We encourage every developer and researchers to call for at least one code review after significant amount of codes were written. Design review is an important step to discuss design issue

14、s before any codes were written. Architectural design review can be complicated and may require several rounds of review meetings. Common models used during design review are described in the book Design Patterns. The AT group can help with code review and design review. Debugging and Stabilization:

15、 RAID is the most commonly used bug tracking and progress tracking tool in Microsoft. Any people who find bugs in any Microsoft developed software may use RAID to log bug against the software developer. These people can be tester engineer, developer himself, program manager, customers, your buddy de

16、velopers, researchers, etc. RAID is famous for its strong query and logging capability. We strongly encourage every developers and researchers to use RAID to track bugs and project progress. Please see the “RAID” document for more details on how to use RAID. Your Machine Environment The research lab

17、, compared to a product team, is more flexible in terms of build tools, and one may choose to use the latest bleeding edge compilers and SDKs at ones own discretion as long as efficiency isnt too disrupted. There are standard tools that we use for builds and tracking projects. Most of these will com

18、e with the install image on your machine, and more can be installed from msrcnxsoftware and bjs-dds-01products. In particular, you should note Microsoft Visual Studio.NET, Source Depot, NT Builds, and RAID. You can find more specific information on use of these within the lab at the links above. Kno

19、w Your Resources The corporate portal site is http:/msw, and you can visit it each workday to find out news about the company and industry, and search for information on corporate policy, career development, and searching the intranet for other information. There are many online resources for genera

20、l development from the corporate website. You can find online tutorials at our Internal Technical Education site. The Productivity internal site discusses general developer productivity issues. The Toolbox is a good place to look for general utilities and tools to increase your efficiency. For conve

21、nience, most useful network addresses and internal websites are listed: Corporate portal sitehttp:/msw MSR Webhttp:/msrweb/search/mssearch.asp MSR info webhttp:/msrinfo Internal Technical Educationhttp:/mste Softwaremsrcnxsoftware; bjs-dds-01products Toolboxhttp:/toolbox/ Productivityhttp:/productiv

22、ity/ Source Depothttp:/tools/ToolCenter/SrcDptToolCtr.asp RAIDhttp:/tools/ToolCenter/RaidToolCtr.asp ITG webhttp:/itgweb/ Microsoft Public download MSDN Required Reading List Found at our on-site library: Writing Solid Code Other Recommended Reading Found at our on-site library: Code Complete, Desig

23、n Patterns, Rapid Development, Dynamics of Software Development, The Mythical Man-Month, Programming Pearls. Papers: Anchoring the Software Process, Why Software Fails, Software Requirements Negotiation Modification History DateWhoChange 1/10/2002BarnWLCreated 1/11/2002BinlinAdd more details to prac

24、tices Coding Style Guidelines Introduction The purpose of standardizing a coding style for a development team or project is to reduce friction in the development process. What does it matter if we name our variables or indent our braces in one way or another? To the perspective of a modern compiler,

25、 it obviously does not matter. But more importantly, the discipline of a shared style increases overall efficiency, in terms of readability and understanding of the source code- not only to teammates and other individuals that may need to understand, review, and debug and maintain others works, but

26、the author himself returning a year from now to update a project, would benefit. With the time saved from trying to get past unfamiliar styles to understand the intent of each others source code, we can make more significant improvements to our programs. Now doesnt that sound more fun and rewarding?

27、 It is the intent of this document to provide a guideline to a shared style for our C+ source code. Most of the guides here have been taken from other such documents from teams within Microsoft. Some of the guides may seem arbitrary, but it is more important to agree upon a single style rather than

28、finesse from the diverse opinions. As a rule, when modifying code that doesnt fit the guidelines set in this document, please either match the different coding style of the function, or modify the entire function to the correct style. Finally, this document shouldnt be etched in stone. As opinions c

29、hange and the team develops, this document should be periodically brought out and reviewed for changes in content and guidelines. Please read and follow our guidelines, you will see the benefit. Thank you for being a good development citizen! Naming Conventions General Naming Conventions PrefixExamp

30、les ClassesCCELEventFrame, CSlide InterfacesIIMediaControl MethodsInvalidate, OnMouseDown Private FunctionsApplyStyle, Draw Data membersm_m_valid, m_idleCounter Static data memberss_s_eventPump, s_topOfStack VariablescurSlp, ghostPat Global variablesg_g_fOleInit, g_pTypeLib Constants, EnumerationsPa

31、ckage- prefix_GR_STYLEPLAIN, TX_ALIGNLEFT, W_PANE_NOERASEBG Type Prefix pPointer to (32-bit is now assumed; thus no need for lp). ppPointer to a pointer hHandle to, aka cookie or abstract pointer (illegal to dereference). refReference to (eg: when passing parameters by reference in C+). rgArray of (

32、ie: items stored sequentially in memory). Note: rg is often used. zTerminated array of. szCHAR *,String, C type (ie: array of 8-bit characters, null character terminated) or CString wszWCHAR *, Unicode string. tszTCHAR *, Flexible Unicode/DBCS string. vecVector matMatrix Type Indicator sSHORTSigned

33、integer, 16-bit. lLONGSigned integer, 32-bit. usUSHORTUnsigned integer, 16-bit. ulULONGUnsigned integer, 32-bit. bBYTENon-counting purposes, 8-bit allocation. wWORDNon-counting purposes, 16-bit allocation. dwDWORDNon-counting purposes, 32-bit allocation. iintScalable signed integer uUINTScalable uns

34、igned integer flfloatFloating point, 32-bit, 6-7 significant digits. ddoubleFloating point, 64-bit, 15-16 signigicant digits. chCHARCharacter, 8-bit. wchWCHARCharacter, Unicode, 16-bit. tchTCHARCharacter, flexible Unicode or DBCS. fnFunctionFunction: always used with a type prefix (eg: pfn is pointe

35、r to function). vvoidVoid: always used with a type prefix (eg: pv is pointer to void). fbool or BOOLf means flag varVARIANT or variant_t Certain abbreviations have become standard abbreviationWord srcSource dstDestination rcRectangle quadQuadrilateral ptPoint txText ptrPointer statStatus or state cm

36、dCommand idIdentifier wndWindow btnButton selSelect or Selection Member Function Names We highly recommend using the following standard prefixes for member function names. Function prefixType of function FQuery operations that return a bool GetGets a property. Set or PutSets a property. Create Dup C

37、reates or duplicates a C+ object. Use “Duplicate” for a method that duplicates the object itself. Objects returned by these functions must be disposed with delete. On After Protected notification methods usually overridden by clients. Where both On and After methods are provided, On is called prior

38、to the event, and After is called after. Draw Move Modifier operations (named with active verb phrases). SwapSwaps the contents of one object with the contents of another in a way guaranteed to succeed and not throw an exception. Code formatting Indentation No Tab character Make sure all tab charact

39、er converted to 4 spaces. Indent level One indent level is 4 spaces Indent data declarations and executable statements one level / Example of function definition PCOMMSG ComGetMsg( PCOMSERVER pServer, long lTimeOut) /- Data indented same level as code PCOMMSG pMsg; /- Code indented one level pMsg =

40、ComReadMsgFromQueue( pServer, NULL, ComWait_c, lTimeOut ); if ( NULL = pMsg ) ErrReport( “Server connection broken” ); return pMsg; Indent function and data declarations at least one additional level beyond the public, protected, and private keywords. class CExample /- public, protected and private

41、functions indented. public: /- Member function declarations indented at least on additional level CExample(); CExample(); private: #ifdef _DEBUG void TraceValue( int iValue ); #endif /- public, protected and private data members indented. private: /- Data declarations indented one level int m_iStore

42、Something; ; Indent long function calls pMsg = ComReadMsgFromQueue( aServer, NULL, ComWait_c, lTimeOut ); Brace Use Braces to mark the beginning and end of all compound statement aligned vertically with their parent block. while (foo) if (bar) Yabba(dabba); else foo(); Xyz(abc); Statements that have

43、 bodies should put those bodies on a separate line and braces should always be used even if the body is only a single line. for( ) if ( ) else if ( ) else White Spaces and line breaks The maximum line length is 80 characters Leave at least one space between a binary operator and each of its operands

44、; use extra spaces to align operands if this improves readability: iA = iB + iC; iMinimum = -iAmplitude; cLetter = *pChar; flY = ( flX * flSlope ) + flY0; x = ( pEvent-m_iButton = iButtonPress ) Never end a line with a space or tab. Have a blank line between variable declarations and code. BOOL FFoo

45、(void) BAR bar1, bar2; int cbar; / There is a blank line below. cbar = Bar( return cbar = 0; Spaces are always AVOIDED in the following places: Between the function name and the left parenthesis, e.g. “Foo (” Between a pointer and the variable it modifies, e.g. “FOO * pfoo” Next to arrows, e.g. “a-

46、b”; Next to variable/dot combinations, e.g. “a. b” Spaces are always USED in the following places: Around keywords, e.g. “if (.)” and never “if(.)”. Between argument/variable combinations in parentheses, e.g. “(a, b, c)” Between a type and a pointer, e.g. “FOO *pfoo” Surrounding equals signs, e.g. “

47、a = b;” and never “a=b;” In summary, spaces are placed as in English (e.g. space after comma, no space after parentheses, space after keywords, space before and after most operators). Never have multiple statements on one line like a = 1; b = 2; / bogus if (fFoo) Bar(); / bogus Labels are always on

48、lines by themselves. LFoo: a = 1; / bogus Syntax Common Types Use the built-in types (short, int, long, etc.).If it requires limit types used, its recommend to redefine all types used in a common header file. Structs struct POINTD / use this REAL X; REAL Y; ; typedef struct tagPOINTD / Do not use this REAL X; REAL Y; POINTD; Const-correctness Use const wherever an item wont be changed. HRESULT Compress(BYTE *pbOut, DWORD *pbOutLen, const BYTE* pbSrc, const DWORD dwSrcLen); Type casts Use explicit typecast force compiler and programmer to more verification. int *ptr = (int