More Related Content Similar to Intro to Software Engineering - Coding Standards Similar to Intro to Software Engineering - Coding Standards (20) More from Radu_Negulescu (14) Intro to Software Engineering - Coding Standards2. 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 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 27. 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)
28. 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
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 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 50. 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 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 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?
56. 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 73. 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 ! 77. LI LI LI LI VROGQWVROGQWVROGQWVROGQW ! DQG VDOHV ! 81. LI LI LI LI VROGQWVROGQWVROGQWVROGQW ! 85. 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
86. 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 94. ^
GR VRPHWKLQJ GR VRPHWKLQJ GR VRPHWKLQJ GR VRPHWKLQJ
` `` `` `` `
IRU L L Q L 103. 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
104. 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
105. 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?
106. 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
107. 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 121. 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
122. 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
123. 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 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 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)
129. 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
130. 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)
131. 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]”
132. 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 141. 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
142. 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 146. SURSHUW
51 6HSW DGG
51 6HSW DGG
51 6HSW DGG
51 6HSW DGG XOXOXOXO OUOUOUOU SURSHUWLHVSURSHUWLHVSURSHUWLHVSURSHUWLHV
RSULJKW 150. 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
151. 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
152. 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 173. 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 ! 185. ^
_
_
_
_
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 210. 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
211. 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
212. 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
213. 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
214. 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”
215. 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
216. 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 224. ^`
````
• 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
225. 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 258. 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 261. ````
• To register/deregister a property change listener, call:
SXEOLF YRLGSXEOLF YRLGSXEOLF YRLGSXEOLF YRLG DGG3URSHUWKDQJH/LVWHQHUDGG3URSHUWKDQJH/LVWHQHUDGG3URSHUWKDQJH/LVWHQHUDGG3URSHUWKDQJH/LVWHQHU 3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU [ 265. SXEOLF YRLGSXEOLF YRLGSXEOLF YRLGSXEOLF YRLG UHPRYH3URSHUWKDQJH/LVWHQHUUHPRYH3URSHUWKDQJH/LVWHQHUUHPRYH3URSHUWKDQJH/LVWHQHUUHPRYH3URSHUWKDQJH/LVWHQHU 3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU3URSHUWKDQJH/LVWHQHU [ 269. • On the listener side, implement method:
SXEOLF YRLGSXEOLF YRLGSXEOLF YRLGSXEOLF YRLG 3URSHUWKDQJH3URSHUWKDQJH3URSHUWKDQJH3URSHUWKDQJH3URSHUWKDQJH(YHQW3URSHUWKDQJH(YHQW3URSHUWKDQJH(YHQW3URSHUWKDQJH(YHQW H 274. 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
275. 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' 288. 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, ...
289. 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...
290. 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
291. 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”, ...
292. 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