Intro to Software Engineering - Coding Standards

1.
Coding standards McGill ECSE321 Introduction to Software Engineering Radu Negulescu Fall 2003

2.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 2 About this module Coding and documentation standards • Important for team communication • Essential for component-based development E.g. Java Beans Customs eventually become law... • Introduce many of the general principles software engineering Bridge the gap between programming and software engineering Contents • Code conventions: layout, naming, comments, etc. Focus on reasons and principles! • Component standards Java Beans essentials • Technical documentation

3.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 3 Why use code conventions? Danger! Religious wars! • Some programmers would rather quit than put a curly bracket in a different place. Then, why bother them with coding conventions? • Not for aesthetics! • Team integration Needs of code readers (reviewers and maintainers) are at least as important as the needs of the code writers! Developers, testers often communicate by code No such thing as “best conventions” More important to follow some consistent conventions Focus on reasons behind, link to organizational objectives • Source code may need to be released with the product • Part of certain development processes “If you are going to have all these programmers (…) refactoring each other’s code constantly, you simply cannot afford to have different sets of coding practices.” [Kent Beck, “Extreme Programming Explained”]

4.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 4 Why use code conventions? Support the following activities on the code: • Reading and understanding Explain the intent Help decypher the meaning and behavior • Retrieving quickly a desired part of the code • Maintaining the code • Preparing for reuse Porting to multiple contexts Use in unforeseen contexts

5.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 5 Code layout How to achieve good code layout? • “Fundamental principle”: highlight logical structure of the code • Proximity: keep related things close together • Maintainability: facilitate editing • Consistency • Compactness

6.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 6 Fundamental principle of code layout Layout should highlight the logical structure of the code! • Resemble the structure of chapters and sections in a book • Example of bad layout (why is it bad?): IRU L L Q L

7.
IRU L L Q L

8.
IRU L L Q L

9.
IRU L L Q L

10.
DL@ WHPSDL@ WHPSDL@WHPSDL@ WHPS WHPSWHPSWHPSWHPS • Avoid embellishments! Embellishments distract attention from logical structure • Align elements that belong together E.g. indent block statements by the same amount • Parentheses: use more of them LI D E F G

11.
EDGLI D EF G

12.
EDGLI D EF G

13.
EDGLI D EF G

14.
EDG LI D E

15.
F G

17.
JRRGLI D E

18.
F G

20.
JRRGLI D E

21.
F G

23.
JRRGLI D E

24.
F G

26.
JRRG

27.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 7 Proximity Group things that are related • Keep comments close to what they describe (we’ll discuss later) • Group related statements E.g. [after McC.]: ZLQGRZGLPHQVLRQVZLQGRZGLPHQVLRQVZLQGRZGLPHQVLRQVZLQGRZGLPHQVLRQV HGLW:LQGRZHGLW:LQGRZHGLW:LQGRZHGLW:LQGRZGLPHQVLRQVGLPHQVLRQVGLPHQVLRQVGLPHQVLRQV ZLQGRZWLWOHZLQGRZWLWOHZLQGRZWLWOHZLQGRZWLWOH HGLW:LQGRZHGLW:LQGRZHGLW:LQGRZHGLW:LQGRZWLWOHWLWOHWLWOHWLWOH FXUVRUVWDUWFXUVRUVWDUWFXUVRUVWDUWFXUVRUVWDUW VWDUWLQJ6FDQ/LQHVWDUWLQJ6FDQ/LQHVWDUWLQJ6FDQ/LQHVWDUWLQJ6FDQ/LQH FXUVRUHQGFXUVRUHQGFXUVRUHQGFXUVRUHQG HQGLQJ6FDQ/LQHHQGLQJ6FDQ/LQHHQGLQJ6FDQ/LQHHQGLQJ6FDQ/LQH FXUVRUFXUVRUFXUVRUFXUVRUEOLQN5DWHEOLQN5DWHEOLQN5DWHEOLQN5DWH HGLW0RGHHGLW0RGHHGLW0RGHHGLW0RGHEOLQN5DWHEOLQN5DWHEOLQN5DWHEOLQN5DWH Separate things that are unrelated • Insert a blank line before a paragraph • Use one file per program module (enforced in Java)

28.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 8 Maintainability Make it easy to cut and paste related text • E.g. use “new style” C function parameters: VWUFSVWUFSVWUFSVWUFS FKDU W GHVWLQDWLRQ VWULQJ FKDU W GHVWLQDWLRQ VWULQJ FKDU W GHVWLQDWLRQ VWULQJ FKDU W GHVWLQDWLRQ VWULQJ FKDU V VRXUFH VWULQJ FKDU V VRXUFH VWULQJ FKDU V VRXUFH VWULQJ FKDU V VRXUFH VWULQJ

32.
^ VWUFSVWUFSVWUFSVWUFS W V

33.
W V

34.
W V

35.
W V

36.
FKDU W V FKDU W V FKDU W V FKDU W V GHVWGHVWGHVWGHVW VWULQJ VRXUFH VWULQJ VWULQJ VRXUFH VWULQJ VWULQJ VRXUFH VWULQJ VWULQJ VRXUFH VWULQJ ^^^^ Make it hard to move unrelated text • Use one statement per line • “New style” C routine declarations also help here Make it hard to edit things by mistake • Class and method Javadoc comments • File headers “New style” parameters “Old style” parameters

37.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 9 Consistency Avoid exceptions from usual layout conventions • E.g. braces around a single-statement block reduce the chance of error in case you need to add more statements to the block LI FRQGLWLRQ

38.
^LI FRQGLWLRQ

39.
^LI FRQGLWLRQ

40.
^LI FRQGLWLRQ

41.
^ VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW ```` LI FRQGLWLRQ

42.
^LI FRQGLWLRQ

43.
^LI FRQGLWLRQ

44.
^LI FRQGLWLRQ

45.
^ VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW ```` LI FRQGLWLRQ

46.
LI FRQGLWLRQ

47.
LI FRQGLWLRQ

48.
LI FRQGLWLRQ

49.
VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW Multi-statement block Layout similarto multi-statement blocks Exception from usual layout convention for multi-statement blocks

50.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 10 Compactness Optimal amount of blank lines: 8-16% Optimal amount of indentation: 2-4 spaces • OR, a tab (but not both tab and spaces!) Avoid redundancy • New style vs. old style C function prototypes VWUFSVWUFSVWUFSVWUFS W V

51.
W V

52.
W V

53.
W V

54.
FKDU W V FKDU W V FKDU W V FKDU W V GHVWGHVWGHVWGHVW VWULQJ VRXUFH VWULQJ VWULQJ VRXUFH VWULQJ VWULQJ VRXUFH VWULQJ VWULQJ VRXUFH VWULQJ ^^^^

55.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 11 Other layout conventions Continuation lines • Indent continuation lines by a larger amount • Break after a comma or before an operator • In the case of multi-line comments, break at the end of a complete phrase Follows from principles?

56.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 12 Selecting a layout (Adapted from [McC.]) • Compact block layout: LI LI LI LI SL[HORORUSL[HORORUSL[HORORUSL[HORORU UHGRORUUHGRORUUHGRORUUHGRORU

60.
^ VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW ```` • More lines,some separation: LI LI LI LI SL[HORORUSL[HORORUSL[HORORUSL[HORORU UHGRORUUHGRORUUHGRORUUHGRORU

64.
^^^^ VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW ```` • More lines,more indenting levels: LI LI LI LI SL[HORORUSL[HORORUSL[HORORUSL[HORORU UHGRORUUHGRORUUHGRORUUHGRORU

68.
^^^^ VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW ```` • More lines,misleading alignment: LI LI LI LI SL[HORORUSL[HORORUSL[HORORUSL[HORORU UHGRORUUHGRORUUHGRORUUHGRORU

72.
^^^^ VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW ````

73.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 13 Selecting a layout Endline layout vs. block layout • Endline layout is bad most of the time E.g. LI LI LI LI VROGQWVROGQWVROGQWVROGQW ! DQG VDOHV !

74.
! DQGVDOHV !

75.
! DQGVDOHV !

76.
! DQGVDOHV !

77.
LI LI LILI VROGQWVROGQWVROGQWVROGQW ! DQG VDOHV !

78.
! DQGVDOHV !

79.
! DQGVDOHV !

80.
! DQGVDOHV !

81.
LI LI LILI VROGQWVROGQWVROGQWVROGQW !

82.
PDUNGRZQ !

83.
PDUNGRZQ !

84.
PDUNGRZQ !

85.
PDUNGRZQ HOVHPDUNGRZQ HOVH PDUNGRZQ HOVH PDUNGRZQ HOVH PDUNGRZQ HOVH PDUNGRZQ HOVH PDUNGRZQ HOVH PDUNGRZQ HOVH PDUNGRZQ HOVH PDUNGRZQ HOVH PDUNGRZQ HOVH PDUNGRZQ HOVH PDUNGRZQ Pro: scraps a few lines Cons: poor maintainability (modifications move more code than they should); inconsistency (not sustainable for larger structures); non-uniformity • Endline layout is good for certain comments tied to the line E.g. a comment that indicates the role of a declared variable FKDU V VRXUFH VWULQJFKDU V VRXUFH VWULQJFKDU V VRXUFH VWULQJFKDU V VRXUFH VWULQJ

86.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 14 Selecting a layout What is good or bad about the following layouts: IRU L L Q L

87.
^IRU L L Q L

88.
^IRU L L Q L

89.
^IRU L L Q L

90.
^ IRU M M Q M

91.
^IRU M M Q M

92.
^IRU M M Q M

93.
^IRU M M Q M

94.
^ GR VRPHWKLQJGR VRPHWKLQJ GR VRPHWKLQJ GR VRPHWKLQJ ` `` `` `` ` IRU L L Q L

95.
^IRU L L Q L

96.
^IRU L L Q L

97.
^IRU L L Q L

98.
^ IRU M M Q M

99.
^IRU M M Q M

100.
^IRU M M Q M

101.
^IRU M M Q M

102.
^ GR VRPHWKLQJGR VRPHWKLQJ GR VRPHWKLQJ GR VRPHWKLQJ ```` ````

103.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 15 Naming “In well-written code, comments are the icing on the readability cake.” [McC.,p.456] How to choose an identifier? • Adequacy • Problem-orientation • Readability • Compactness • Follow expectations • Follow conventions

104.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 16 Adequacy Accurately and completely describe the named item • Variable, class, method, etc. E.g., a variable that represents the current date • Good names: CurrentDate, CrntDate • Bad names: CD, Current, C, X, X1, Date, PreDate OK to use single-character names for “throw-away” local variables • Loop counters and limits • Unused exceptions • Unused events Too cryptic Incomplete Cryptic AND incomplete Inaccurate Incomplete

105.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 17 Problem-orientation The identifier should tell what the item does, not how it is implemented • E.g. BookTitle rather than LongString • Other examples?

106.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 18 Compactness Where possible, keep it short • Single-character names for local throw-away variables • Avoid cryptic “license-plate” acronyms (trmn8) Take time to read Look garbled • A long name may indicate poor modularity getEmployeeSalaryAndBenefitsPolicyAndSetNewValuesDependingOnFlag(...) split into getEmployeeSalary(...), getEmployeeBenefits(...), setEmployeeSalary(...), setEmployeeBenefits(...), checkFlag(...), ... • Method names tend to be longer than variable names For completeness reasons

107.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 19 Follow expectations Principle of “minimal surprise” • Use similar names for related things, opposite pairs, etc. Good: upperRight, lowerLeft Bad: UR, downcorner • Think of the contexts of usage of a label 7UHH6HW7UHH6HW7UHH6HW7UHH6HW IUDFWDO QHZIUDFWDO QHZIUDFWDO QHZIUDFWDO QHZ 7UHH6HW7UHH6HW7UHH6HW7UHH6HW

108.
LI IUDFWDOLI IUDFWDOLIIUDFWDOLI IUDFWDOKDV'UDZ,QIRKDV'UDZ,QIRKDV'UDZ,QIRKDV'UDZ,QIR

110.
^

112.
^

114.
^

116.
^ IUDFWDOGUDZ

117.
IUDFWDOGUDZ

118.
IUDFWDOGUDZ

119.
IUDFWDOGUDZ

120.
```` Boolean return type usedin condition label “has…” reads well after “if” and noun “TreeSet” reads well -before noun -after “new”

121.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 20 Follow conventions Classes, interfaces, types: • Nouns • Umbrella-label for all the elements (objects) of the class “Wheel3DEvent”, “Window”, “ArrayOutOfBoundsException”, “Object” • Mixed case, starting with a capital Methods, functions: • Verbs: drawPicture, addElement, isInitialized • Mixed case, starting with a lower case Constants: • Upper case File names: • README for directory content description; GNUmakefile or Makefile for conditional compilation files See Java conventions document

122.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 21 Comments Are comments helpful? • See play “The Commento” [Handout - McC., pp.458-461] How to achieve good commenting? • Relevance • Maintainability • Document surprises • Hierarchy

123.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 22 Relevance Use comments sparingly! • Comments introduce redundancy maintenance overhead! • Know which types of comments are worth including • Keep each comment succint! • Avoid comments that simply repeat the code E.g. [adapted from McC.] VHW SURGXFW WR EDVH VHW SURGXFW WR EDVH VHW SURGXFW WR EDVH VHW SURGXFW WR EDVH SURGXFW EDVHSURGXFW EDVHSURGXFW EDVHSURGXFW EDVH ORRS IURP WR QXP ORRS IURP WR QXP ORRS IURP WR QXP ORRS IURP WR QXP IRU L L QXP L

124.
^IRU L L QXP L

125.
^IRU L L QXP L

126.
^IRU L L QXP L

127.
^ SURGXFW SURGXFW EDVHSURGXFW SURGXFW EDVHSURGXFW SURGXFW EDVHSURGXFW SURGXFW EDVH ```` Redundant comment. Hard to maintain if num is changed to num-1

128.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 23 Maintainability Comments need to be maintained just like the rest of the code • Make comments easy to edit • Except where they are not supposed to change Principle of proximity: keep comments close to the code they describe • Avoid endline in general • Use endline where tied to the line Data declarations, maintenance notes Include maintenance notes (date of revision, author, etc) • Developer’s markers (“to fix later” flag)

129.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 24 Other commenting practices Document surprises Distinguish major comments • Underline, overline, use ellipses • Hierarchy of subtitles

130.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 25 Useful comments Subtitles (PDL) Assertions (pre-conditions, post-conditions, invariants) Data comments Maintenance notes (file headers, to-do, change log) Tags • Documentation (e.g. Javadoc tags) • Instrumentation (e.g. iContract tags)

131.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 26 Subtitle comments Say what the code does, rather than how • Give a higher level of abstraction than the code • Use pseudocode (PDL) lines as subtitle-type comments E.g. 6HW ZLQGRZ SDUDPHWHUV 6HW ZLQGRZ SDUDPHWHUV 6HW ZLQGRZ SDUDPHWHUV 6HW ZLQGRZ SDUDPHWHUV ZLQGRZGLPHQVLRQVZLQGRZGLPHQVLRQVZLQGRZGLPHQVLRQVZLQGRZGLPHQVLRQV HGLW:LQGRZHGLW:LQGRZHGLW:LQGRZHGLW:LQGRZGLPHQVLRQVGLPHQVLRQVGLPHQVLRQVGLPHQVLRQV ZLQGRZWLWOHZLQGRZWLWOHZLQGRZWLWOHZLQGRZWLWOH HGLW:LQGRZHGLW:LQGRZHGLW:LQGRZHGLW:LQGRZWLWOHWLWOHWLWOHWLWOH 6HW FXUVRU SDUDPHWHUV 6HW FXUVRU SDUDPHWHUV 6HW FXUVRU SDUDPHWHUV 6HW FXUVRU SDUDPHWHUV FXUVRUVWDUWFXUVRUVWDUWFXUVRUVWDUWFXUVRUVWDUW VWDUWLQJ6FDQ/LQHVWDUWLQJ6FDQ/LQHVWDUWLQJ6FDQ/LQHVWDUWLQJ6FDQ/LQH FXUVRUHQGFXUVRUHQGFXUVRUHQGFXUVRUHQG HQGLQJ6FDQ/LQHHQGLQJ6FDQ/LQHHQGLQJ6FDQ/LQHHQGLQJ6FDQ/LQH FXUVRUFXUVRUFXUVRUFXUVRUEOLQN5DWHEOLQN5DWHEOLQN5DWHEOLQN5DWH HGLW0RGHHGLW0RGHHGLW0RGHHGLW0RGHEOLQN5DWHEOLQN5DWHEOLQN5DWHEOLQN5DWH • Annotate data declarations: role, data invariants E.g. “array a contains distinct values only” Or, equivalently, “forall i, j: a[i] != a[j]”

132.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 27 Assertion comments Pre-conditions, post-conditions, invariants • E.g. after [BD, p.239] +DVKWDEOH+DVKWDEOH+DVKWDEOH+DVKWDEOH FODVV 0DLQWDLQV PDSSLQJV IURP XQLTXH NHV WR DUELWUDU REMHFWVFODVV 0DLQWDLQV PDSSLQJV IURP XQLTXH NHV WR DUELWUDU REMHFWVFODVV 0DLQWDLQV PDSSLQJV IURP XQLTXH NHV WR DUELWUDU REMHFWVFODVV 0DLQWDLQV PDSSLQJV IURP XQLTXH NHV WR DUELWUDU REMHFWV FODVVFODVVFODVVFODVV +DVKWDEOH+DVKWDEOH+DVKWDEOH+DVKWDEOH ^^^^ 7KH QXPEHU RI HOHPHQWV LQ 7KH QXPEHU RI HOHPHQWV LQ 7KH QXPEHU RI HOHPHQWV LQ 7KH QXPEHU RI HOHPHQWV LQ +DVKWDEOH+DVKWDEOH+DVKWDEOH+DVKWDEOH LV DOZDV QRQLV DOZDV QRQLV DOZDV QRQLV DOZDV QRQQHJDWLYHQHJDWLYHQHJDWLYHQHJDWLYH SULYDWHSULYDWHSULYDWHSULYDWH LQWLQWLQWLQW QXP(OHPHQWVQXP(OHPHQWVQXP(OHPHQWVQXP(OHPHQWV 7KH SXW RSHUDWLRQ 7KH SXW RSHUDWLRQ 7KH SXW RSHUDWLRQ 7KH SXW RSHUDWLRQ DVVXPHV WKDW WKH VSHFLILHG NH LV QRW XVHGDVVXPHV WKDW WKH VSHFLILHG NH LV QRW XVHGDVVXPHV WKDW WKH VSHFLILHG NH LV QRW XVHGDVVXPHV WKDW WKH VSHFLILHG NH LV QRW XVHG $IWHU WKH SXW RSHUDWLRQ LV FRPSOHWHG$IWHU WKH SXW RSHUDWLRQ LV FRPSOHWHG$IWHU WKH SXW RSHUDWLRQ LV FRPSOHWHG$IWHU WKH SXW RSHUDWLRQ LV FRPSOHWHGWKH VSHFLILHG NH FDQ EH XVHGWKH VSHFLILHG NH FDQ EH XVHGWKH VSHFLILHG NH FDQ EH XVHGWKH VSHFLILHG NH FDQ EH XVHG WR WR WR WR UHFRYHU WKH HQWUUHFRYHU WKH HQWUUHFRYHU WKH HQWUUHFRYHU WKH HQWU ZLWK WKH JHWNH

133.
RSHUDWLRQ ZLWK WKHJHWNH

134.

135.

136.
RSHUDWLRQ SXEOLF YRLGSXW 2EMHFW NH 2EMHFW HQWU

137.
^SXEOLF YRLG SXW2EMHFW NH 2EMHFW HQWU

138.

139.

140.
^

141.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 28 Data comments Role (meaning) of data fields and specific invariants • At declaration For consistency • Endline layout recommended here SURWHFWHG 3RLQWSURWHFWHG 3RLQWSURWHFWHG 3RLQWSURWHFWHG 3RLQW OOOOOOOO ORZHU OHIW FRUQHUORZHU OHIW FRUQHUORZHU OHIW FRUQHUORZHU OHIW FRUQHU [ ! [ ! [ ! [ ! SURWHFWHGSURWHFWHGSURWHFWHGSURWHFWHG LQWLQWLQWLQW ZLGWKZLGWKZLGWKZLGWK ! ! ! ! SURWHFWHGSURWHFWHGSURWHFWHGSURWHFWHG LQWLQWLQWLQW KHLJKWKHLJKWKHLJKWKHLJKW ! ! ! ! Meaning Invariant Meaning is self-documented

142.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 29 Maintenance notes File headers • Title, author, creation date • Change log • IP rights notice 0XOWLRUQHU%R[%HDQ0XOWLRUQHU%R[%HDQ0XOWLRUQHU%R[%HDQ0XOWLRUQHU%R[%HDQMDYDMDYDMDYDMDYD UHDWHG RQ 6HSWHPEHU $0 UHDWHG RQ 6HSWHPEHU $0 UHDWHG RQ 6HSWHPEHU $0 UHDWHG RQ 6HSWHPEHU $0 KDQJHV KDQJHV KDQJHV KDQJHV 51 6HSW DGG 51 6HSW DGG 51 6HSW DGG 51 6HSW DGG XUXUXUXU XSSHU5LJKWXSSHU5LJKWXSSHU5LJKWXSSHU5LJKW

143.
SURSHUW

144.
SURSHUW

145.
SURSHUW

146.
SURSHUW 51 6HSW DGG 51 6HSW DGG 51 6HSW DGG 51 6HSW DGG XOXOXOXO OUOUOUOU SURSHUWLHVSURSHUWLHVSURSHUWLHVSURSHUWLHV RSULJKW

147.
RSULJKW

148.
RSULJKW

149.
RSULJKW

150.
5DGX 1HJXOHVFX5DGX 1HJXOHVFX5DGX1HJXOHVFX5DGX 1HJXOHVFX To-do notes SULYDWHSULYDWHSULYDWHSULYDWH LQWLQWLQWLQW P,QWP,QWP,QWP,QW 7%' FKDQJH WR ORQJ LQ UHOHDVH 7%' FKDQJH WR ORQJ LQ UHOHDVH 7%' FKDQJH WR ORQJ LQ UHOHDVH 7%' FKDQJH WR ORQJ LQ UHOHDVH

151.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 30 Documentation Tags Generate documentation from in-line comments • Avoid redundancy Javadoc • Java documentation comments /** … */ As opposed to “implementation” comments /* … */ and // Use // for unused code lines • Can be converted to HTML by javadoc • Used to describe classes, interfaces, vars, methods • Placed just before the item commented • Include special tags (@return, @param, @author, …) See Sun site for a list of tags and usage

152.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 31 Instrumentation tags Generate code from in-line comments • Avoids redundancy • Use special language to specify instrumented code E.g. OCL assertions [BD, p.239] 7KH QXPEHU RI HOHPHQWV LQ 7KH QXPEHU RI HOHPHQWV LQ 7KH QXPEHU RI HOHPHQWV LQ 7KH QXPEHU RI HOHPHQWV LQ +DVKWDEOH+DVKWDEOH+DVKWDEOH+DVKWDEOH LV DOZDV QRQLV DOZDV QRQLV DOZDV QRQLV DOZDV QRQQHJDWLYHQHJDWLYHQHJDWLYHQHJDWLYH #LQY #LQY #LQY #LQY QXP(OHPHQWVQXP(OHPHQWVQXP(OHPHQWVQXP(OHPHQWV ! ! ! ! SULYDWHSULYDWHSULYDWHSULYDWH LQW QXP(OHPHQWVLQW QXP(OHPHQWVLQW QXP(OHPHQWVLQW QXP(OHPHQWV 7KH SXW RSHUDWLRQ DVVXPHV WKDW WKH VSHFLILHG NH LV QRW XVH 7KH SXW RSHUDWLRQ DVVXPHV WKDW WKH VSHFLILHG NH LV QRW XVH 7KH SXW RSHUDWLRQ DVVXPHV WKDW WKH VSHFLILHG NH LV QRW XVH 7KH SXW RSHUDWLRQ DVVXPHV WKDW WKH VSHFLILHG NH LV QRW XVHGGGG $IWHU WKH SXW RSHUDWLRQ LV FRPSOHWHGWKH VSHFLILHG NH FDQ $IWHU WKH SXW RSHUDWLRQ LV FRPSOHWHGWKH VSHFLILHG NH FDQ $IWHU WKH SXW RSHUDWLRQ LV FRPSOHWHGWKH VSHFLILHG NH FDQ $IWHU WKH SXW RSHUDWLRQ LV FRPSOHWHGWKH VSHFLILHG NH FDQ EH XVHGEH XVHGEH XVHGEH XVHG WR UHFRYHU WKH HQWU ZLWK WKH JHWNH

153.
RSHUDWLRQ WR UHFRYHUWKH HQWU ZLWK WKH JHWNH

154.

155.

156.
RSHUDWLRQ #SUH FRQWDLQVNH

157.
#SUH FRQWDLQVNH

158.
#SUH FRQWDLQVNH

159.
#SUH FRQWDLQVNH

160.
#SRVW FRQWDLQVNH

161.
#SRVW FRQWDLQVNH

162.
#SRVW FRQWDLQVNH

163.
#SRVW FRQWDLQVNH

164.
#SRVW JHWNH

165.
HQWU #SRVWJHWNH

166.
HQWU #SRVWJHWNH

167.
HQWU #SRVWJHWNH

168.
HQWU SXEOLF YRLGSXW 2EMHFW NH 2EMHFW HQWU

169.

170.

171.

172.
^

173.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 32 Instrumentation comments Assertion-checking with iContract tools • Comment pre-conditions, post-conditions, and invariants in a subset of “object constraint language” (OCL) • iContract inserts Java code for run-time assertion checking (“instrumented code”) • The instrumented code throws RuntimeExceptions if assertion is false • The code can also be compiled for release without assertion checking • Example of code generated from @pre (n = 0) _ _ _ _ LQWLQWLQWLQW BBUHWXUQBYDOXHBKROGHUBBBUHWXUQBYDOXHBKROGHUBBBUHWXUQBYDOXHBKROGHUBBBUHWXUQBYDOXHBKROGHUB _ _ _ _ ERROHDQERROHDQERROHDQERROHDQ BBSUHBSDVVHG IDOVH WUXH LI SUHBBSUHBSDVVHG IDOVH WUXH LI SUHBBSUHBSDVVHG IDOVH WUXH LI SUHBBSUHBSDVVHG IDOVH WUXH LI SUHFRQGFRQGFRQGFRQG SDVVHGSDVVHGSDVVHGSDVVHG _ LI _ LI _ LI _ LI Q !

174.
Q !

175.
Q !

176.
Q !

178.
BBSUHBSDVVHG WUXH VXFFHHGHG

179.

180.

181.
BBSUHBSDVVHG WUXH VXFFHHGHG _ LI _ LI _ LI _ LI BBSUHBSDVVHG

182.
^BBSUHBSDVVHG

183.
^BBSUHBSDVVHG

184.
^BBSUHBSDVVHG

185.
^ _ _ _ _ WKURZ QHZWKURZQHZWKURZ QHZWKURZ QHZ 5XQWLPH([FHSWLRQ5XQWLPH([FHSWLRQ5XQWLPH([FHSWLRQ5XQWLPH([FHSWLRQ ' ' ' '????????WRROVWRROVWRROVWRROV????????,%09-DYD,%09-DYD,%09-DYD,%09-DYD????????,'(,'(,'(,'(????????SURMHFWBUHVRXUFHVSURMHFWBUHVRXUFHVSURMHFWBUHVRXUFHVSURMHFWBUHVRXUFHV????????]]]]????????LURRWLURRWLURRWLURRW????????,5RRW,5RRW,5RRW,5RRWMDYD HUURU SUHFRQGLWLRQMDYD HUURU SUHFRQGLWLRQMDYD HUURU SUHFRQGLWLRQMDYD HUURU SUHFRQGLWLRQ YLRODWHG YLRODWHG YLRODWHG YLRODWHG LURRWLURRWLURRWLURRW,5RRW,5RRW,5RRW,5RRWLURRWLURRWLURRWLURRWLQWLQWLQWLQW

187.
GHFODUHG LQ

189.
GHFODUHG LQ

191.
GHFODUHG LQ

193.
GHFODUHG LQ LURRWLURRWLURRWLURRW,5RRW,5RRW,5RRW,5RRWLURRWLURRWLURRWLURRWLQWLQWLQWLQW

194.
Q !

197.
Q !

200.
Q !

203.
Q !

205.
_

206.
_

207.
_

208.
_

209.
````

210.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 33 Other coding conventions Variable declarations • One per line • Keep related declarations together • Combine declarations with initializations Unless a computed value is needed • Good: 6WULQJ6WULQJ6WULQJ6WULQJ QHZ1XPQHZ1XPQHZ1XPQHZ1XP XVHU LQSXW GLJLWV RQO XVHU LQSXW GLJLWV RQO XVHU LQSXW GLJLWV RQO XVHU LQSXW GLJLWV RQO LQWLQWLQWLQW FXUVRU LQGH[ RI FXUUHQW FKDUDFWHUFXUVRU LQGH[ RI FXUUHQW FKDUDFWHUFXUVRU LQGH[ RI FXUUHQW FKDUDFWHUFXUVRU LQGH[ RI FXUUHQW FKDUDFWHU 2EMHFW2EMHFW2EMHFW2EMHFW FUW(QWUFUW(QWUFUW(QWUFUW(QWU FXUUHQWO VHOHFWHG WDEOH HQWU FXUUHQWO VHOHFWHG WDEOH HQWU FXUUHQWO VHOHFWHG WDEOH HQWU FXUUHQWO VHOHFWHG WDEOH HQWU LQWLQWLQWLQW OHYHO LQGHQWDWLRQ OHYHOOHYHO LQGHQWDWLRQ OHYHOOHYHO LQGHQWDWLRQ OHYHOOHYHO LQGHQWDWLRQ OHYHO • Not so good (harder to change): 6WULQJ6WULQJ6WULQJ6WULQJ QHZ1XPQHZ1XPQHZ1XPQHZ1XP XVHU LQSXW GLJLWV RQO XVHU LQSXW GLJLWV RQO XVHU LQSXW GLJLWV RQO XVHU LQSXW GLJLWV RQO 2EMHFW2EMHFW2EMHFW2EMHFW FUW(QWUFUW(QWUFUW(QWUFUW(QWU FXUUHQWO VHOHFWHG WDEOH HQWU FXUUHQWO VHOHFWHG WDEOH HQWU FXUUHQWO VHOHFWHG WDEOH HQWU FXUUHQWO VHOHFWHG WDEOH HQWU LQWLQWLQWLQW FXUVRU LQGH[ RI FXUUHQW FKDUDFWHUFXUVRU LQGH[ RI FXUUHQW FKDUDFWHUFXUVRU LQGH[ RI FXUUHQW FKDUDFWHUFXUVRU LQGH[ RI FXUUHQW FKDUDFWHU OHYHO LQGHQWDWLRQ OHYHOOHYHO LQGHQWDWLRQ OHYHOOHYHO LQGHQWDWLRQ OHYHOOHYHO LQGHQWDWLRQ OHYHO • Pretty bad: LQWLQWLQWLQW FXUVRU OHYHO FXUVRU OHYHO FXUVRU OHYHO FXUVRU OHYHO • Put declarations at the beginning of a block

211.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 34 Other coding conventions Order of the entries in class and interface declarations • Data fields • Constructor methods • Observer methods • Mutator methods • Producer methods

212.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 35 Component-based development Idea: What makes a component? Components vs. component instances Component = classes, resources, etc. Component instance = customized and connected objects Sebastian’sMegablocksComponents©RaduNegulescu,2003

213.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 36 Component standards Origins: compound documents • Xerox Star (-) • Apple’s Hypercard (-) • OpenDoc (-) • Visual Basic: embed controls into forms • OLE: allow controls to be arbitrary document servers and containers at the same time • Web pages: step back to VB forms • New VB: ActiveX controls can be containers too • OMG’s CORBA, IDL • Microsoft: COM, COM+, DCOM • Sun: Java Beans • Microsoft: .NET Assemblies We’ll cover a few Java Beans features as an example

214.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 37 Java Beans Java applets • Mini applications launched by a browser or other environment • Applets are isolated from whatever executes in the same environment Two applets can run in the same browser, but cannot interact except by talking to the server side • Applets are not downloaded together with their own image or resource files Java Beans • Java Beans specification (JavaSoft, 1996) • Unlike applets, a Bean can talk to other components on a web page • The term “Bean” refers both to “component” and “component instance”

215.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 38 Java Beans Java Beans have been conceived for dual usage • “Design time”: assemble the beans with a tool E.g. set-up the properties through dialogs, customize behavior, graphically set up connections • “Run time”: normal functionality Used interactively (graphical and I/O operations) Used non-interactively (skip the GUI operations) • A bean instance can inquire whether it is at design time or run time, and whether it is used interactively or not Any class can be a bean • What makes a bean usable as a bean is the adherence to a set of conventions

216.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 39 Java Beans properties Java Beans properties = attributes (fields) exposed by pairs of getter and setter methods SXEOLF FODVVSXEOLF FODVVSXEOLF FODVVSXEOLF FODVV 0ODVV0ODVV0ODVV0ODVV ^^^^ SURWHFWHGSURWHFWHGSURWHFWHGSURWHFWHG LQW YDOLQW YDOLQW YDOLQW YDO SXEOLFSXEOLFSXEOLFSXEOLF LQWLQWLQWLQW JHW9DOJHW9DOJHW9DOJHW9DO

217.
^`

218.
^`

219.
^`

220.
^` SXEOLF YRLGSXEOLF YRLGSXEOLFYRLGSXEOLF YRLG VHW9DOVHW9DOVHW9DOVHW9DOLQW QHZYDOLQW QHZYDOLQW QHZYDOLQW QHZYDO

221.
^`

222.
^`

223.
^`

224.
^` ```` • Can beaccessed by property sheets (customization) Both at design time and run time • Java Beans “design pattern”: really a naming convention General “design pattern”: setXyz, getXyz as above Boolean “design pattern”: differs by method isPropertyName • Maintainability: change implementation while keeping the interface C# calls getters and setters automatically on each evaluation assignment

225.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 40 Java Beans properties An example SXEOLF FODVVSXEOLF FODVVSXEOLF FODVVSXEOLF FODVV 0%R[0%R[0%R[0%R[ ^^^^ SURWHFWHG 3RLQWSURWHFWHG 3RLQWSURWHFWHG 3RLQWSURWHFWHG 3RLQW OOOOOOOO ORZHU OHIW FRUQHU [ ! ORZHU OHIW FRUQHU [ ! ORZHU OHIW FRUQHU [ ! ORZHU OHIW FRUQHU [ ! SURWHFWHGSURWHFWHGSURWHFWHGSURWHFWHG LQWLQWLQWLQW ZLGWK ! ZLGWK ! ZLGWK ! ZLGWK ! SURWHFWHGSURWHFWHGSURWHFWHGSURWHFWHG LQWLQWLQWLQW KHLJKW ! KHLJKW ! KHLJKW ! KHLJKW ! QR XSSHU ULJKW FRUQHU QR XSSHU ULJKW FRUQHU QR XSSHU ULJKW FRUQHU QR XSSHU ULJKW FRUQHU SXEOLF 3RLQWSXEOLF 3RLQWSXEOLF 3RLQWSXEOLF 3RLQW JHW/OJHW/OJHW/OJHW/O

226.
^`

227.
^`

228.
^`

229.
^` SXEOLF YRLGSXEOLF YRLGSXEOLFYRLGSXEOLF YRLG VHW/OVHW/OVHW/OVHW/O3RLQW3RLQW3RLQW3RLQW QHZOOQHZOOQHZOOQHZOO

230.
^`

231.
^`

232.
^`

233.
^` SXEOLFSXEOLFSXEOLFSXEOLF LQW JHW:LGWKLQWJHW:LGWKLQW JHW:LGWKLQW JHW:LGWK

234.
^`

235.
^`

236.
^`

237.
^` SXEOLF YRLGSXEOLF YRLGSXEOLFYRLGSXEOLF YRLG VHW:LGWKVHW:LGWKVHW:LGWKVHW:LGWKLQW QHZ:LGWKLQW QHZ:LGWKLQW QHZ:LGWKLQW QHZ:LGWK

238.
^`

239.
^`

240.
^`

241.
^` SXEOLFSXEOLFSXEOLFSXEOLF LQW JHW+HLJKWLQWJHW+HLJKWLQW JHW+HLJKWLQW JHW+HLJKW

242.
^`

243.
^`

244.
^`

245.
^` SXEOLF YRLGSXEOLF YRLGSXEOLFYRLGSXEOLF YRLG VHW+HLJKWVHW+HLJKWVHW+HLJKWVHW+HLJKWLQW QHZ+HLJKWLQW QHZ+HLJKWLQW QHZ+HLJKWLQW QHZ+HLJKW

246.
^`

247.
^`

248.
^`

249.
^` SXEOLF 3RLQWSXEOLF 3RLQWSXEOLF3RLQWSXEOLF 3RLQW JHW8UJHW8UJHW8UJHW8U

250.
^`

251.
^`

252.
^`

253.
^` SXEOLF YRLGSXEOLF YRLGSXEOLFYRLGSXEOLF YRLG VHW8UVHW8UVHW8UVHW8U3RLQW3RLQW3RLQW3RLQW QHZ8UQHZ8UQHZ8UQHZ8U

254.
^`

255.
^`

256.
^`

257.
^` ````

258.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 41 Java Beans properties Indexed properties • Array attribute • Permits access by getter and setter, plus an indexed form Bound properties • Changes in a bound property will trigger events that will notify listeners of the change SXEOLF FODVVSXEOLF FODVVSXEOLF FODVVSXEOLF FODVV 3URSHUWKDQJH(YHQW3URSHUWKDQJH(YHQW3URSHUWKDQJH(YHQW3URSHUWKDQJH(YHQW H[WHQGV MDYDXWLOH[WHQGV MDYDXWLOH[WHQGV MDYDXWLOH[WHQGV MDYDXWLO(YHQW2EMHFW(YHQW2EMHFW(YHQW2EMHFW(YHQW2EMHFW ^^^^ SXEOLF 2EMHFWSXEOLF 2EMHFWSXEOLF 2EMHFWSXEOLF 2EMHFW JHW1HZ9DOXHJHW1HZ9DOXHJHW1HZ9DOXHJHW1HZ9DOXH

259.
SXEOLF 2EMHFWSXEOLF 2EMHFWSXEOLF2EMHFWSXEOLF 2EMHFW JHW2OG9DOXHJHW2OG9DOXHJHW2OG9DOXHJHW2OG9DOXH

260.
SXEOLF 6WULQJSXEOLF 6WULQJSXEOLF6WULQJSXEOLF 6WULQJ JHW3URSHUW1DPHJHW3URSHUW1DPHJHW3URSHUW1DPHJHW3URSHUW1DPH

261.
```` • To register/deregistera property change listener, call: SXEOLF YRLGSXEOLF YRLGSXEOLF YRLGSXEOLF YRLG DGG3URSHUWKDQJH/LVWHQHUDGG3URSHUWKDQJH/LVWHQHUDGG3URSHUWKDQJH/LVWHQHUDGG3URSHUWKDQJH/LVWHQHU 3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU [

262.
[

263.
[

264.
[

265.
SXEOLF YRLGSXEOLF YRLGSXEOLFYRLGSXEOLF YRLG UHPRYH3URSHUWKDQJH/LVWHQHUUHPRYH3URSHUWKDQJH/LVWHQHUUHPRYH3URSHUWKDQJH/LVWHQHUUHPRYH3URSHUWKDQJH/LVWHQHU 3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU [

266.
[

267.
[

268.
[

269.
• On thelistener side, implement method: SXEOLF YRLGSXEOLF YRLGSXEOLF YRLGSXEOLF YRLG 3URSHUWKDQJH3URSHUWKDQJH3URSHUWKDQJH3URSHUWKDQJH3URSHUWKDQJH(YHQW3URSHUWKDQJH(YHQW3URSHUWKDQJH(YHQW3URSHUWKDQJH(YHQW H

270.
^ `H

271.
^ `H

272.
^ `H

273.
^ ` Constrained properties •Changes and events are vetoable and reversible

274.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 42 Event-based control The state of the event source is communicated to the event listener • Event object passed as parameter to event handler method • Use an “event” object, parameter to handler method • Used in many foundation class libraries “Generalization of Observer pattern” Source register (Listener) unregister (Listener) cast (Event) Listener handle (Event) *1 ConcreteListener listenerState handle (Event) ConcreteSource subjectState cast (Event) * 1 listenerState = event.getState(); Event copyState getState () *1 create new Event e; for each registered Listener l l.handle(e); event (YHQW VRXUFH (YHQW OLVWHQHUV

275.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 43 Java Beans events and connections Java Beans event model • Event listeners Need to implement an interface that extends java.beans.EventListener Have a handler method for each event the listener listens to LQWHUIDFH :KHHO'/LVWHQHU H[WHQGV MDYDXWLOLQWHUIDFH :KHHO'/LVWHQHU H[WHQGV MDYDXWLOLQWHUIDFH :KHHO'/LVWHQHU H[WHQGV MDYDXWLOLQWHUIDFH :KHHO'/LVWHQHU H[WHQGV MDYDXWLO(YHQW/LVWHQHU(YHQW/LVWHQHU(YHQW/LVWHQHU(YHQW/LVWHQHU ^^^^ YRLG ZKHHO'

276.
YRLG ZKHHO'

277.
YRLG ZKHHO'

278.
YRLG ZKHHO'

279.
```` • Event sources Providepairs of register and unregister methods SXEOLF YRLG DGG:KHHO'/LVWHQHU:KHHO'/LVWHQHU O

280.
SXEOLF YRLG DGG:KHHO'/LVWHQHU:KHHO'/LVWHQHUO

281.

282.

283.
SXEOLF YRLG UHPRYH:KHHO'/LVWHQHU:KHHO'/LVWHQHUO

284.

285.

286.

287.
• Event adapters Mergeevent streams Both listener and source Can perform arbitrary filtering functions

288.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 44 JAR files JAR (Java Archive) files are compressed files that can package several beans and auxiliary resources • PKZIP archive format • Class files Possibly, several beans • Serialized objects representing bean prototypes (instances) Contain state information (customization, field values) • Optionally, a manifest file Contents of the archive • Optional help files in HTML • Optional localization information • Resource files needed by the bean Icons GIF, JPEG, ...

289.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 45 Technical documents Guidelines for: specifications, manuals, design, change plans, the code itself, notes, messages, etc. What is important for the technical documentation for software? • Correctness, completeness, aspect, ... • Maintainability, concision, navigability, consistency, clarity, ... Keep in mind the purpose - what needs to be done with the document • Consult for detail information – precise, clear • Browse for specific information – easy to navigate • Modify often, keep consistency – maintainable • Convey an image • NOT entertainment...

290.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 46 Technical documents Maintainability! • Documentation needs to be updated and corrected, just like code Documentation should be modular, just like code • Avoid: redundant, repetitious text Invites consistency problems whenever changes are made Good: say something in one place, insert cross-reference in the other place “Window envelope” principle Redundancy is useful in some situations, but it better have a good excuse Support cross-checks Support quick high-level view • Avoid: amalgamated text Good: isolate ideas, keep each sentence focused, summarize each paragraph in the opening sentence • Avoid: update help files and user manuals independently Good: obtain manuals automatically from help files, or obtain both from code (e.g. by javadoc) Good: or, obtain both manually from the specification documents

291.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 47 Technical documents Concision! • “Concision does not mean omission of detail, but that every word tell” ---Strunk White • Bad: inclusion of lecture notes in a design document Good: rationale for your design decisions Navigability! • How easy is it to find the relevant information? • Bad: unstructured text Good: table of contents, cross-references, hyperlinks, index of terms Consistency! • Consistent style facilitates information retrieval Unlike literary writing, technical writing is not made better by style variation Clarity! • E.g. avoid ambiguous expressions: “it”, “this”, ...

292.
McGill University ECSE321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 48 References Generic coding conventions • Layout: McConnell ch. 18 • Comments: McConnell ch. 19 • Naming: McConnell ch. 9, sect. 5.2 Java coding conventions ftp://ftp.javasoft.com/docs/codeconv/CodeConventions.pdf Java Beans http://java.sun.com/products/javabeans/ C coding conventions http://www.cs.mcgill.ca/resourcepages/indian-hill.html Javadoc http://java.sun.com/products/jdk/javadoc/writingdoccomments.html iContract tools http://www.reliable-systems.com/tools/iContract/iContract.htm

Intro to Software Engineering - Coding Standards

More Related Content

Similar to Intro to Software Engineering - Coding Standards

More from Radu_Negulescu

Recently uploaded

Intro to Software Engineering - Coding Standards