Your SlideShare is downloading. ×
0
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Intro to Software Engineering - Coding Standards
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Intro to Software Engineering - Coding Standards

389

Published on

Published in: Technology, Education
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
389
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
5
Comments
0
Likes
1
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 1. Coding standards McGill ECSE 321 Introduction to Software Engineering Radu Negulescu Fall 2003
  • 2. McGill University ECSE 321 © 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 ECSE 321 © 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 ECSE 321 © 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 ECSE 321 © 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 ECSE 321 © 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 E F G
  • 12. EDGLI D E F G
  • 13. EDGLI D E F G
  • 14. EDG LI D E
  • 15. F G
  • 16. JRRGLI D E
  • 17. F G
  • 18. JRRGLI D E
  • 19. F G
  • 20. JRRGLI D E
  • 21. F G
  • 22. JRRG
  • 23. McGill University ECSE 321 © 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)
  • 24. McGill University ECSE 321 © 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
  • 25. ^
  • 26. ^
  • 27. ^
  • 28. ^ VWUFSVWUFSVWUFSVWUFS W V
  • 29. W V
  • 30. W V
  • 31. W V
  • 32. 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
  • 33. McGill University ECSE 321 © 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
  • 34. ^LI FRQGLWLRQ
  • 35. ^LI FRQGLWLRQ
  • 36. ^LI FRQGLWLRQ
  • 37. ^ VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW ```` LI FRQGLWLRQ
  • 38. ^LI FRQGLWLRQ
  • 39. ^LI FRQGLWLRQ
  • 40. ^LI FRQGLWLRQ
  • 41. ^ VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW ```` LI FRQGLWLRQ
  • 42. LI FRQGLWLRQ
  • 43. LI FRQGLWLRQ
  • 44. LI FRQGLWLRQ
  • 45. VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW Multi-statement block Layout similar to multi-statement blocks Exception from usual layout convention for multi-statement blocks
  • 46. McGill University ECSE 321 © 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
  • 47. W V
  • 48. W V
  • 49. W V
  • 50. 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 ^^^^
  • 51. McGill University ECSE 321 © 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?
  • 52. McGill University ECSE 321 © 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
  • 53. ^
  • 54. ^
  • 55. ^
  • 56. ^ VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW ```` • More lines, some separation: LI LI LI LI SL[HORORUSL[HORORUSL[HORORUSL[HORORU UHGRORUUHGRORUUHGRORUUHGRORU
  • 57. ^^^^ VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW ```` • More lines, more indenting levels: LI LI LI LI SL[HORORUSL[HORORUSL[HORORUSL[HORORU UHGRORUUHGRORUUHGRORUUHGRORU
  • 58. ^^^^ VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW ```` • More lines, misleading alignment: LI LI LI LI SL[HORORUSL[HORORUSL[HORORUSL[HORORU UHGRORUUHGRORUUHGRORUUHGRORU
  • 59. ^^^^ VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW VWDWHPHQWVWDWHPHQWVWDWHPHQWVWDWHPHQW ````
  • 60. McGill University ECSE 321 © 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 !
  • 61. ! DQG VDOHV !
  • 62. ! DQG VDOHV !
  • 63. ! DQG VDOHV !
  • 64. LI LI LI LI VROGQWVROGQWVROGQWVROGQW ! DQG VDOHV !
  • 65. ! DQG VDOHV !
  • 66. ! DQG VDOHV !
  • 67. ! DQG VDOHV !
  • 68. LI LI LI LI VROGQWVROGQWVROGQWVROGQW !
  • 69. PDUNGRZQ !
  • 70. PDUNGRZQ !
  • 71. PDUNGRZQ !
  • 72. PDUNGRZQ HOVH PDUNGRZQ 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
  • 73. McGill University ECSE 321 © 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
  • 74. ^IRU L L Q L
  • 75. ^IRU L L Q L
  • 76. ^IRU L L Q L
  • 77. ^ IRU M M Q M
  • 78. ^IRU M M Q M
  • 79. ^IRU M M Q M
  • 80. ^IRU M M Q M
  • 81. ^ GR VRPHWKLQJ GR VRPHWKLQJ GR VRPHWKLQJ GR VRPHWKLQJ ` `` `` `` ` IRU L L Q L
  • 82. ^IRU L L Q L
  • 83. ^IRU L L Q L
  • 84. ^IRU L L Q L
  • 85. ^ IRU M M Q M
  • 86. ^IRU M M Q M
  • 87. ^IRU M M Q M
  • 88. ^IRU M M Q M
  • 89. ^ GR VRPHWKLQJ GR VRPHWKLQJ GR VRPHWKLQJ GR VRPHWKLQJ ```` ````
  • 90. McGill University ECSE 321 © 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
  • 91. McGill University ECSE 321 © 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
  • 92. McGill University ECSE 321 © 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?
  • 93. McGill University ECSE 321 © 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
  • 94. McGill University ECSE 321 © 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
  • 95. LI IUDFWDOLI IUDFWDOLI IUDFWDOLI IUDFWDOKDV'UDZ,QIRKDV'UDZ,QIRKDV'UDZ,QIRKDV'UDZ,QIR
  • 96. ^
  • 97. ^
  • 98. ^
  • 99. ^ IUDFWDOGUDZ
  • 100. IUDFWDOGUDZ
  • 101. IUDFWDOGUDZ
  • 102. IUDFWDOGUDZ
  • 103. ```` Boolean return type used in condition label “has…” reads well after “if” and noun “TreeSet” reads well -before noun -after “new”
  • 104. McGill University ECSE 321 © 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
  • 105. McGill University ECSE 321 © 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
  • 106. McGill University ECSE 321 © 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
  • 107. ^IRU L L QXP L
  • 108. ^IRU L L QXP L
  • 109. ^IRU L L QXP L
  • 110. ^ SURGXFW SURGXFW EDVHSURGXFW SURGXFW EDVHSURGXFW SURGXFW EDVHSURGXFW SURGXFW EDVH ```` Redundant comment. Hard to maintain if num is changed to num-1
  • 111. McGill University ECSE 321 © 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)
  • 112. McGill University ECSE 321 © 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
  • 113. McGill University ECSE 321 © 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)
  • 114. McGill University ECSE 321 © 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]”
  • 115. McGill University ECSE 321 © 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
  • 116. RSHUDWLRQ ZLWK WKH JHWNH
  • 117. RSHUDWLRQ ZLWK WKH JHWNH
  • 118. RSHUDWLRQ ZLWK WKH JHWNH
  • 119. RSHUDWLRQ SXEOLF YRLG SXW 2EMHFW NH 2EMHFW HQWU
  • 120. ^SXEOLF YRLG SXW 2EMHFW NH 2EMHFW HQWU
  • 121. ^SXEOLF YRLG SXW 2EMHFW NH 2EMHFW HQWU
  • 122. ^SXEOLF YRLG SXW 2EMHFW NH 2EMHFW HQWU
  • 123. ^
  • 124. McGill University ECSE 321 © 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
  • 125. McGill University ECSE 321 © 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
  • 126. SURSHUW
  • 127. SURSHUW
  • 128. SURSHUW
  • 129. SURSHUW 51 6HSW DGG 51 6HSW DGG 51 6HSW DGG 51 6HSW DGG XOXOXOXO OUOUOUOU SURSHUWLHVSURSHUWLHVSURSHUWLHVSURSHUWLHV RSULJKW
  • 130. RSULJKW
  • 131. RSULJKW
  • 132. RSULJKW
  • 133. 5DGX 1HJXOHVFX5DGX 1HJXOHVFX5DGX 1HJXOHVFX5DGX 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
  • 134. McGill University ECSE 321 © 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
  • 135. McGill University ECSE 321 © 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
  • 136. RSHUDWLRQ WR UHFRYHU WKH HQWU ZLWK WKH JHWNH
  • 137. RSHUDWLRQ WR UHFRYHU WKH HQWU ZLWK WKH JHWNH
  • 138. RSHUDWLRQ WR UHFRYHU WKH HQWU ZLWK WKH JHWNH
  • 139. RSHUDWLRQ #SUH FRQWDLQVNH
  • 140. #SUH FRQWDLQVNH
  • 141. #SUH FRQWDLQVNH
  • 142. #SUH FRQWDLQVNH
  • 143. #SRVW FRQWDLQVNH
  • 144. #SRVW FRQWDLQVNH
  • 145. #SRVW FRQWDLQVNH
  • 146. #SRVW FRQWDLQVNH
  • 147. #SRVW JHWNH
  • 148. HQWU #SRVW JHWNH
  • 149. HQWU #SRVW JHWNH
  • 150. HQWU #SRVW JHWNH
  • 151. HQWU SXEOLF YRLG SXW 2EMHFW NH 2EMHFW HQWU
  • 152. ^SXEOLF YRLG SXW 2EMHFW NH 2EMHFW HQWU
  • 153. ^SXEOLF YRLG SXW 2EMHFW NH 2EMHFW HQWU
  • 154. ^SXEOLF YRLG SXW 2EMHFW NH 2EMHFW HQWU
  • 155. ^
  • 156. McGill University ECSE 321 © 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 !
  • 157. Q !
  • 158. Q !
  • 159. Q !
  • 160. BBSUHBSDVVHG WUXH VXFFHHGHG
  • 161. BBSUHBSDVVHG WUXH VXFFHHGHG
  • 162. BBSUHBSDVVHG WUXH VXFFHHGHG
  • 163. BBSUHBSDVVHG WUXH VXFFHHGHG _ LI _ LI _ LI _ LI BBSUHBSDVVHG
  • 164. ^BBSUHBSDVVHG
  • 165. ^BBSUHBSDVVHG
  • 166. ^BBSUHBSDVVHG
  • 167. ^ _ _ _ _ WKURZ QHZWKURZ QHZWKURZ 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
  • 168. GHFODUHG LQ
  • 169. GHFODUHG LQ
  • 170. GHFODUHG LQ
  • 171. GHFODUHG LQ LURRWLURRWLURRWLURRW,5RRW,5RRW,5RRW,5RRWLURRWLURRWLURRWLURRWLQWLQWLQWLQW
  • 172. Q !
  • 173. Q !
  • 174. Q !
  • 175. Q !
  • 176. _
  • 177. _
  • 178. _
  • 179. _
  • 180. ````
  • 181. McGill University ECSE 321 © 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
  • 182. McGill University ECSE 321 © 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
  • 183. McGill University ECSE 321 © 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
  • 184. McGill University ECSE 321 © 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
  • 185. McGill University ECSE 321 © 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”
  • 186. McGill University ECSE 321 © 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
  • 187. McGill University ECSE 321 © 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
  • 188. ^`
  • 189. ^`
  • 190. ^`
  • 191. ^` SXEOLF YRLGSXEOLF YRLGSXEOLF YRLGSXEOLF YRLG VHW9DOVHW9DOVHW9DOVHW9DOLQW QHZYDOLQW QHZYDOLQW QHZYDOLQW QHZYDO
  • 192. ^`
  • 193. ^`
  • 194. ^`
  • 195. ^` ```` • Can be accessed 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
  • 196. McGill University ECSE 321 © 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
  • 197. ^`
  • 198. ^`
  • 199. ^`
  • 200. ^` SXEOLF YRLGSXEOLF YRLGSXEOLF YRLGSXEOLF YRLG VHW/OVHW/OVHW/OVHW/O3RLQW3RLQW3RLQW3RLQW QHZOOQHZOOQHZOOQHZOO
  • 201. ^`
  • 202. ^`
  • 203. ^`
  • 204. ^` SXEOLFSXEOLFSXEOLFSXEOLF LQW JHW:LGWKLQW JHW:LGWKLQW JHW:LGWKLQW JHW:LGWK
  • 205. ^`
  • 206. ^`
  • 207. ^`
  • 208. ^` SXEOLF YRLGSXEOLF YRLGSXEOLF YRLGSXEOLF YRLG VHW:LGWKVHW:LGWKVHW:LGWKVHW:LGWKLQW QHZ:LGWKLQW QHZ:LGWKLQW QHZ:LGWKLQW QHZ:LGWK
  • 209. ^`
  • 210. ^`
  • 211. ^`
  • 212. ^` SXEOLFSXEOLFSXEOLFSXEOLF LQW JHW+HLJKWLQW JHW+HLJKWLQW JHW+HLJKWLQW JHW+HLJKW
  • 213. ^`
  • 214. ^`
  • 215. ^`
  • 216. ^` SXEOLF YRLGSXEOLF YRLGSXEOLF YRLGSXEOLF YRLG VHW+HLJKWVHW+HLJKWVHW+HLJKWVHW+HLJKWLQW QHZ+HLJKWLQW QHZ+HLJKWLQW QHZ+HLJKWLQW QHZ+HLJKW
  • 217. ^`
  • 218. ^`
  • 219. ^`
  • 220. ^` SXEOLF 3RLQWSXEOLF 3RLQWSXEOLF 3RLQWSXEOLF 3RLQW JHW8UJHW8UJHW8UJHW8U
  • 221. ^`
  • 222. ^`
  • 223. ^`
  • 224. ^` SXEOLF YRLGSXEOLF YRLGSXEOLF YRLGSXEOLF YRLG VHW8UVHW8UVHW8UVHW8U3RLQW3RLQW3RLQW3RLQW QHZ8UQHZ8UQHZ8UQHZ8U
  • 225. ^`
  • 226. ^`
  • 227. ^`
  • 228. ^` ````
  • 229. McGill University ECSE 321 © 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
  • 230. SXEOLF 2EMHFWSXEOLF 2EMHFWSXEOLF 2EMHFWSXEOLF 2EMHFW JHW2OG9DOXHJHW2OG9DOXHJHW2OG9DOXHJHW2OG9DOXH
  • 231. SXEOLF 6WULQJSXEOLF 6WULQJSXEOLF 6WULQJSXEOLF 6WULQJ JHW3URSHUW1DPHJHW3URSHUW1DPHJHW3URSHUW1DPHJHW3URSHUW1DPH
  • 232. ```` • To register/deregister a property change listener, call: SXEOLF YRLGSXEOLF YRLGSXEOLF YRLGSXEOLF YRLG DGG3URSHUWKDQJH/LVWHQHUDGG3URSHUWKDQJH/LVWHQHUDGG3URSHUWKDQJH/LVWHQHUDGG3URSHUWKDQJH/LVWHQHU 3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU [
  • 233. [
  • 234. [
  • 235. [
  • 236. SXEOLF YRLGSXEOLF YRLGSXEOLF YRLGSXEOLF YRLG UHPRYH3URSHUWKDQJH/LVWHQHUUHPRYH3URSHUWKDQJH/LVWHQHUUHPRYH3URSHUWKDQJH/LVWHQHUUHPRYH3URSHUWKDQJH/LVWHQHU 3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU [
  • 237. [
  • 238. [
  • 239. [
  • 240. • On the listener side, implement method: SXEOLF YRLGSXEOLF YRLGSXEOLF YRLGSXEOLF YRLG 3URSHUWKDQJH3URSHUWKDQJH3URSHUWKDQJH3URSHUWKDQJH3URSHUWKDQJH(YHQW3URSHUWKDQJH(YHQW3URSHUWKDQJH(YHQW3URSHUWKDQJH(YHQW H
  • 241. ^ `H
  • 242. ^ `H
  • 243. ^ `H
  • 244. ^ ` Constrained properties • Changes and events are vetoable and reversible
  • 245. McGill University ECSE 321 © 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
  • 246. McGill University ECSE 321 © 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'
  • 247. YRLG ZKHHO'
  • 248. YRLG ZKHHO'
  • 249. YRLG ZKHHO'
  • 250. ```` • Event sources Provide pairs of register and unregister methods SXEOLF YRLG DGG:KHHO'/LVWHQHU:KHHO'/LVWHQHU O
  • 251. SXEOLF YRLG DGG:KHHO'/LVWHQHU:KHHO'/LVWHQHU O
  • 252. SXEOLF YRLG DGG:KHHO'/LVWHQHU:KHHO'/LVWHQHU O
  • 253. SXEOLF YRLG DGG:KHHO'/LVWHQHU:KHHO'/LVWHQHU O
  • 254. SXEOLF YRLG UHPRYH:KHHO'/LVWHQHU:KHHO'/LVWHQHU O
  • 255. SXEOLF YRLG UHPRYH:KHHO'/LVWHQHU:KHHO'/LVWHQHU O
  • 256. SXEOLF YRLG UHPRYH:KHHO'/LVWHQHU:KHHO'/LVWHQHU O
  • 257. SXEOLF YRLG UHPRYH:KHHO'/LVWHQHU:KHHO'/LVWHQHU O
  • 258. • Event adapters Merge event streams Both listener and source Can perform arbitrary filtering functions
  • 259. McGill University ECSE 321 © 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, ...
  • 260. McGill University ECSE 321 © 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...
  • 261. McGill University ECSE 321 © 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
  • 262. McGill University ECSE 321 © 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”, ...
  • 263. McGill University ECSE 321 © 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

×