intro to software engineering - coding standards

48
Coding standards McGill ECSE 321 Introduction to Software Engineering Radu Negulescu Fall 2003

Upload: radunegulescu

Post on 06-Sep-2014

444 views

Category:

Technology


8 download

DESCRIPTION

 

TRANSCRIPT

Page 1: Intro to Software Engineering - Coding Standards

Coding standards

McGill ECSE 321Introduction to Software Engineering

Radu Negulescu

Fall 2003

Page 2: Intro to Software Engineering - Coding Standards

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 developmentE.g. Java BeansCustoms eventually become law...

• Introduce many of the general principles software engineeringBridge the gap between programming and software engineering

Contents

• Code conventions: layout, naming, comments, etc.Focus on reasons and principles!

• Component standardsJava Beans essentials

• Technical documentation

Page 3: Intro to Software Engineering - Coding Standards

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 adifferent place. Then, why bother them with coding conventions?

• Not for aesthetics!

• Team integrationNeeds of code readers (reviewers and maintainers) are at least as important as the needs of the code writers!Developers, testers often communicate by codeNo such thing as “best conventions”More important to follow some consistent conventionsFocus 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”]

Page 4: Intro to Software Engineering - Coding Standards

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 understandingExplain the intentHelp decypher the meaning and behavior

• Retrieving quickly a desired part of the code

• Maintaining the code

• Preparing for reusePorting to multiple contextsUse in unforeseen contexts

Page 5: Intro to Software Engineering - Coding Standards

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

Page 6: Intro to Software Engineering - Coding Standards

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?):

�������������������� �������������������� �������������������� ��������������������

��������������������������������������������

������������������������

• Avoid embellishments!Embellishments distract attention from logical structure

• Align elements that belong togetherE.g. indent block statements by the same amount

• Parentheses: use more of them

�������������������� ��������������������������������� ��������������������������������� ��������������������������������� �������������

����������� ����������� ��������������������� ����������� ��������������������� ����������� ��������������������� ����������� ����������

Page 7: Intro to Software Engineering - Coding Standards

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 statementsE.g. [after McC.]:

���������������������������������������������������������������������������� ������������������������������������������������������������������������������������

���������������������������������������������������������������������������� ����������������������������������������������������������������

� ����������������� ����������������� ����������������� ���������������� ��������!���"�����������!���"�����������!���"�����������!���"���

� ����������������� ����������������� ����������������� ���������������� ������!���"���������!���"���������!���"���������!���"���

� ������ ������ ������ ���������#$�������#$�������#$�������#$��� ���� ����%�������%�������%�������%�����������#$�������#$�������#$�������#$���

Separate things that are unrelated

• Insert a blank line before a paragraph

• Use one file per program module (enforced in Java)

Page 8: Intro to Software Engineering - Coding Standards

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:

�����&�����&�����&�����& ����

�'���(�)���(��������������������(���'���(�)���(��������������������(���'���(�)���(��������������������(���'���(�)���(��������������������(��

�'���(�����(��� �����������(��'���(�����(��� �����������(��'���(�����(��� �����������(��'���(�����(��� �����������(�

�* �* �* �*

������������

�����&�����&�����&�����& ��)�� ��)�� ��)�� ��)��

�'���(�)�(����(��'���(�)�(����(��'���(�)�(����(��'���(�)�(����(�������������������������)��� �����������(����������)��� �����������(����������)��� �����������(����������)��� �����������(��

****

������������

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

Page 9: Intro to Software Engineering - Coding Standards

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

������������� �*��������������� �*��������������� �*��������������� �*��

���������+���������+���������+���������+

���������,���������,���������,���������,

���������-���������-���������-���������-

.�.�.�.�

������������� �*��������������� �*��������������� �*��������������� �*��

���������+���������+���������+���������+

.�.�.�.�

������������� ������������� ������������� �������������

���������+���������+���������+���������+

Multi-statement block

Layout similar to multi-statement blocks

Exception from usual layout convention for multi-statement blocks

Page 10: Intro to Software Engineering - Coding Standards

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

�����&�����&�����&�����& ��)�� ��)�� ��)�� ��)��

�'���(�)�(����(�'���(�)�(����(�'���(�)�(����(�'���(�)�(����( ������������������������)��� �����������(����������)��� �����������(����������)��� �����������(����������)��� �����������(��

****

������������

Page 11: Intro to Software Engineering - Coding Standards

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?

Page 12: Intro to Software Engineering - Coding Standards

McGill University ECSE 321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 12

Selecting a layout

(Adapted from [McC.])

• Compact block layout:

�������������������������������������������� ���� ���������� ���� ���� ���� ��������������

��������������������������������������������

��������������������������������������������

������������

����

• More lines, some separation:

�������������������������������������������� ���� ���������� ���� ���� ���� ������

����

��������������������������������������������

��������������������������������������������

������������

����

• More lines, more indenting levels:

�������������������������������������������� ���� ���� �� ���� ���� ���� ������

����

��������������������������������������������

��������������������������������������������

������������

����

• More lines, misleading alignment:

�������������������������������������������� ���� ���� �� ���� ���� ���� ������

����

��������������������������������������������

��������������������������������������������

������������

����

Page 13: Intro to Software Engineering - Coding Standards

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 timeE.g.

��������������������/������/������/������/�� 0�+������������0�+� 0�+������������0�+� 0�+������������0�+� 0�+������������0�+�

��������������������/������/������/������/�� 0�+�������������0�+� 0�+�������������0�+� 0�+�������������0�+� 0�+�������������0�+�

��������������������/������/������/������/�� 0�+��� ����#�����1����+�0�+��� ����#�����1����+�0�+��� ����#�����1����+�0�+��� ����#�����1����+�

��������#�����1�����2��������#�����1�����2��������#�����1�����2��������#�����1�����2

��������#����������,��������#����������,��������#����������,��������#����������,

��������#�����1�����������#�����1�����������#�����1�����������#�����1���

Pro: scraps a few linesCons: 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 lineE.g. a comment that indicates the role of a declared variable

�'���(��������� �����������'���(��������� �����������'���(��������� �����������'���(��������� ����������

Page 14: Intro to Software Engineering - Coding Standards

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:

�������������������� �*�������������������� �*�������������������� �*�������������������� �*

�����3�����3����3��� �*�����3�����3����3��� �*�����3�����3����3��� �*�����3�����3����3��� �*

�����������'��������������'��������������'��������������'���

.�..�..�..�.

������������������� �*������������������� �*������������������� �*������������������� �*

�����3�����3����3�� �*�����3�����3����3�� �*�����3�����3����3�� �*�����3�����3����3�� �*

�����������'��������������'��������������'��������������'���

....

....

Page 15: Intro to Software Engineering - Coding Standards

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

Page 16: Intro to Software Engineering - Coding Standards

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

Page 17: Intro to Software Engineering - Coding Standards

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?

Page 18: Intro to Software Engineering - Coding Standards

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 readLook garbled

• A long name may indicate poor modularitygetEmployeeSalaryAndBenefitsPolicyAndSetNewValuesDependingOnFlag(...) split into getEmployeeSalary(...), getEmployeeBenefits(...), setEmployeeSalary(...), setEmployeeBenefits(...), checkFlag(...), ...

• Method names tend to be longer than variable namesFor completeness reasons

Page 19: Intro to Software Engineering - Coding Standards

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, lowerLeftBad: UR, downcorner

• Think of the contexts of usage of a label

4���!��4���!��4���!��4���!�� ���������������������������������������������������� 4���!��4���!��4���!��4���!��� � � �

������������������������������������������������'��5���6���'��5���6���'��5���6���'��5���6���� �*� �*� �*� �*

������������� ������������� ������������� �������������

....

Boolean return typeused in conditionlabel “has…” reads

well after “if” and noun

“TreeSet” reads well-before noun-after “new”

Page 20: Intro to Software Engineering - Coding Standards

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 Makefilefor conditional compilation files

See Java conventions document

Page 21: Intro to Software Engineering - Coding Standards

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

Page 22: Intro to Software Engineering - Coding Standards

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 codeE.g. [adapted from McC.]

�(��������� �����������(��(��������� �����������(��(��������� �����������(��(��������� �����������(�

���� ������������� ������������� ������������� ���������

�(�����������,����� ��(��(�����������,����� ��(��(�����������,����� ��(��(�����������,����� ��(�

���������,����� ������ �*���������,����� ������ �*���������,����� ������ �*���������,����� ������ �*

���� ��������� ���(��������� ��������� ���(��������� ��������� ���(��������� ��������� ���(�����

....

Redundant comment.Hard to maintain if num is changed to num-1

Page 23: Intro to Software Engineering - Coding Standards

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 lineData declarations, maintenance notes

Include maintenance notes (date of revision, author, etc)

• Developer’s markers (“to fix later” flag)

Page 24: Intro to Software Engineering - Coding Standards

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

Page 25: Intro to Software Engineering - Coding Standards

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)

Page 26: Intro to Software Engineering - Coding Standards

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 commentsE.g.

���!�����������������������!�����������������������!�����������������������!��������������������

��������������������������������������������������������������������������������������������������������������������������������������������������������������������

������������������������������������������������������������������������������������������������������������������������������������������������

���!���� ������������������!���� ������������������!���� ������������������!���� ���������������

� ������������������ ������������������ ������������������ �������������������������!���"�����������!���"�����������!���"�����������!���"���

� ������������������ ������������������ ������������������ �����������������������!���"���������!���"���������!���"���������!���"���

� ������ ������ ������ ���������#$�������#$�������#$�������#$��� ������������%�������%�������%�������%�����������#$�������#$�������#$�������#$���

• Annotate data declarations: role, data invariantsE.g. “array a contains distinct values only” Or, equivalently, “forall i, j: a[i] != a[j]”

Page 27: Intro to Software Engineering - Coding Standards

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]

�(��(��(��(�7��'�����7��'�����7��'�����7��'����� �������%����������������������� ��8 ��#�&�������������&���3�����������%����������������������� ��8 ��#�&�������������&���3�����������%����������������������� ��8 ��#�&�������������&���3�����������%����������������������� ��8 ��#�&�������������&���3���� (�(�(�(�

������������������������7��'�����7��'�����7��'�����7��'����� ****

�(�4'��� ���������������������(�4'��� ���������������������(�4'��� ���������������������(�4'��� ��������������������7��'�����7��'�����7��'�����7��'����� �������&������������&������������&������������&�����9999������:�������:�������:�������:� (�(�(�(�

���:�������:�������:�������:���������������� � �;�������� �;�������� �;�������� �;�������

�(�4'��� �������������(�4'��� �������������(�4'��� �������������(�4'��� ��������������� �����'����'������������#�&�������� ������ �����'����'������������#�&�������� ������ �����'����'������������#�&�������� ������ �����'����'������������#�&�������� �������

(�(�(�(�<������'��� ������������������������<������'��� ������������������������<������'��� ������������������������<������'��� ������������������������)�'������������#�&�������� ���)�'������������#�&�������� ���)�'������������#�&�������� ���)�'������������#�&�������� ���

(����(����(����(��������:����'������&����:����'������&����:����'������&����:����'������& ���'��'������#�& �����������(����'��'������#�& �����������(����'��'������#�& �����������(����'��'������#�& �����������(�

� �����:����� ���=�3����#�&)�=�3��������& �*� �����:����� ���=�3����#�&)�=�3��������& �*� �����:����� ���=�3����#�&)�=�3��������& �*� �����:����� ���=�3����#�&)�=�3��������& �*

������������

Page 28: Intro to Software Engineering - Coding Standards

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 declarationFor consistency

• Endline layout recommended here

����������>��������������>��������������>��������������>���� �������������������������������������������������������������������������������������������������������� �?)��&�0����?)��&�0����?)��&�0����?)��&�0���

������������������������������������ ������������ ����'����'����'����'������������������������0���0���0���0���

������������������������������������ ������������ '���'�'���'�'���'�'���'���������������������0���0���0���0���

Meaning

Invariant

Meaning isself-documented

Page 29: Intro to Software Engineering - Coding Standards

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�(�(�(�(

(�(�(�(�% ���/�����@�?@���% ���/�����@�?@���% ���/�����@�?@���% ���/�����@�?@����3�:��3�:��3�:��3�:�

((((

(�/����������!���������+)�,��-)�A1BC�<%(�/����������!���������+)�,��-)�A1BC�<%(�/����������!���������+)�,��-)�A1BC�<%(�/����������!���������+)�,��-)�A1BC�<%

((((

(�/'�����1(�/'�����1(�/'�����1(�/'�����1

(�$D)�!����,1�����(�$D)�!����,1�����(�$D)�!����,1�����(�$D)�!����,1����� �� �� �� ������ ����$��'� ����$��'� ����$��'� ����$��'� ��������& ��������& ��������& ��������&

(�$D)�!����-1�����(�$D)�!����-1�����(�$D)�!����-1�����(�$D)�!����-1����� � � � �)�)�)�)��������� ����������������������������������������

((((

(��/��&���'� (��/��&���'� (��/��&���'� (��/��&���'� $�� �D�� ���� $�� �D�� ���� $�� �D�� ���� $�� �D�� ���� )�,��-)�,��-)�,��-)�,��-

(�(�(�(�

To-do notes���:�������:�������:�������:���������������� �&6���&6���&6���&6�������4@51��'��������E����E������������,������4@51��'��������E����E������������,������4@51��'��������E����E������������,������4@51��'��������E����E������������,�

Page 30: Intro to Software Engineering - Coding Standards

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

Page 31: Intro to Software Engineering - Coding Standards

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 codeE.g. OCL assertions [BD, p.239]

�(�4'��� ��������������������(�4'��� ��������������������(�4'��� ��������������������(�4'��� ������������������� 7��'�����7��'�����7��'�����7��'����� �������&������������&������������&������������&�����9999������:��������:��������:��������:��

(�F��:(�F��:(�F��:(�F��: � �;�������� �;�������� �;�������� �;������� 0����(�0����(�0����(�0����(�

���:������:������:������:��� ����� �;������������ �;������������ �;������������ �;�������

�(�4'��� ��������������� �����'����'������������#�&�������� ���(�4'��� ��������������� �����'����'������������#�&�������� ���(�4'��� ��������������� �����'����'������������#�&�������� ���(�4'��� ��������������� �����'����'������������#�&�������� ����������

(�<������'��� ������������������������)�'������������#�&�����(�<������'��� ������������������������)�'������������#�&�����(�<������'��� ������������������������)�'������������#�&�����(�<������'��� ������������������������)�'������������#�&�������� ������ ������ ������ ���

(��������:����'������&����'��'������#�& ����������1(��������:����'������&����'��'������#�& ����������1(��������:����'������&����'��'������#�& ����������1(��������:����'������&����'��'������#�& ����������1

(�F����G���������#�& (�F����G���������#�& (�F����G���������#�& (�F����G���������#�&

(�F��������������#�& (�F��������������#�& (�F��������������#�& (�F��������������#�&

(�F���������#�& ��������&�(�(�F���������#�& ��������&�(�(�F���������#�& ��������&�(�(�F���������#�& ��������&�(�

� �����:����� ���=�3����#�&)�=�3��������& �*� �����:����� ���=�3����#�&)�=�3��������& �*� �����:����� ���=�3����#�&)�=�3��������& �*� �����:����� ���=�3����#�&)�=�3��������& �*

������������

Page 32: Intro to Software Engineering - Coding Standards

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)

������������������������������������ ��������������� � ������������������� � ������������������� � ������������������� � ����

�������������������� !����!����!����!���� ����������� ����������������������������������� ����������������������������������� ����������������������������������� ������������������������""""#� #� #� #� ����� ������ ������ ������ �

�����������������������������������������������$��%����$��%����$��%����$��%���������������� ��������������##�� � ��������������� ��������������##�� � ��������������� ��������������##�� � ��������������� ��������������##�� �

����������������������������������������&&&&����������� �������������� �������������� �������������� ���

��������������������������������� �'���'� �'���'� �'���'� �'���' (������)�#�����(������)�#�����(������)�#�����(������)�#������*+,�*+,�*+,�*+,--------������������--------./012���./012���./012���./012���--------.+).+).+).+)--------��3�#�������#����3�#�������#����3�#�������#����3�#�������#��--------4444--------������������--------.(�.(�.(�.(��3���,�5,�����,����#� ������3���,�5,�����,����#� ������3���,�5,�����,����#� ������3���,�5,�����,����#� ����������� �������� �������� �������� ������������������.(�.(�.(�.(�,,,,,,,,������������������������������,���� �#���� �����,���� �#���� �����,���� �#���� �����,���� �#���� ��� ����������������.(�.(�.(�.(�,,,,,,,,�����������������������������������$��%���*�������$��%���*�������$��%���*�������$��%���*

�������������������������������� ����

Page 33: Intro to Software Engineering - Coding Standards

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 initializationsUnless a computed value is needed

• Good:!������!������!������!���������D ����D ����D ����D ������ ������� �)�����������&����� ������� �)�����������&����� ������� �)�����������&����� ������� �)�����������&

������������ � ����������������?����� �������'�������� ����������������?����� �������'�������� ����������������?����� �������'�������� ����������������?����� �������'�������

=�3����=�3����=�3����=�3�������;���&���;���&���;���&���;���&����� ������&��������������������&����� ������&��������������������&����� ������&��������������������&����� ������&��������������������&

������������ ��:��������������������������:����:��������������������������:����:��������������������������:����:��������������������������:��

• Not so good (harder to change):!������!������!������!���������D ����D ����D ����D ������� ������� �)�����������&������ ������� �)�����������&������ ������� �)�����������&������ ������� �)�����������&

=�3����=�3����=�3����=�3�������;���&���;���&���;���&���;���&����� ������&��������������������&����� ������&��������������������&����� ������&��������������������&����� ������&��������������������&

������������ � ��������)���������?����� �������'�������� ��������)���������?����� �������'�������� ��������)���������?����� �������'�������� ��������)���������?����� �������'�������

��:���������������������������:����:���������������������������:����:���������������������������:����:���������������������������:��

• Pretty bad:������������ � ��������)���:������� ��������)���:������� ��������)���:������� ��������)���:������

• Put declarations at the beginning of a block

Page 34: Intro to Software Engineering - Coding Standards

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

Page 35: Intro to Software Engineering - Coding Standards

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 instancesComponent = classes, resources, etc.Component instance = customized and connected objects

Seb

ast

ian’s

Meg

ablo

cks

Com

pon

ents

©

Radu N

egule

scu,

2003

Page 36: Intro to Software Engineering - Coding Standards

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

Page 37: Intro to Software Engineering - Coding Standards

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 environmentTwo 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”

Page 38: Intro to Software Engineering - Coding Standards

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 toolE.g. set-up the properties through dialogs, customize behavior, graphically set up connections

• “Run time”: normal functionalityUsed 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

Page 39: Intro to Software Engineering - Coding Standards

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

� ������������ ������������ ������������ �����������%&/����%&/����%&/����%&/���� ****

��������������������������������������������:������:������:������:��

� ����� ����� ����� ���� �������������������H�����H�����H�����H��� �*���.� �*���.� �*���.� �*���.

� �����:����� �����:����� �����:����� �����:�������H�����H�����H�����H�������������:���������:���������:���������:�� �*���. �*���. �*���. �*���.

....

• Can be accessed by property sheets (customization)Both at design time and run time

• Java Beans “design pattern”: really a naming conventionGeneral “design pattern”: setXyz, getXyz as aboveBoolean “design pattern”: differs by method is<PropertyName>

• Maintainability: change implementation while keeping the interfaceC# calls getters and setters automatically on each evaluation & assignment

Page 40: Intro to Software Engineering - Coding Standards

McGill University ECSE 321 © 2003 Radu Negulescu Introduction to Software Engineering Coding standards—Slide 40

Java Beans properties

An example

� ������������ ������������ ������������ �����������%&@�?%&@�?%&@�?%&@�? ****

����������>���������������>���������������>���������������>�������������������������������������?)��&�0���������������������������?)��&�0���������������������������?)��&�0���������������������������?)��&�0���

������������������������������������������������������������'�����0�������'�����0�������'�����0�������'�����0���

��������������������������������������������������������'���'������0���'���'������0���'���'������0���'���'������0���

�(���� ��������'��������G�(��(���� ��������'��������G�(��(���� ��������'��������G�(��(���� ��������'��������G�(�

� �����>������ �����>������ �����>������ �����>��������"����"����"����"�� �*���.� �*���.� �*���.� �*���.

� �����:���� �����:���� �����:���� �����:��� ���"����"����"����"��>�����>�����>�����>���� �������������������� �*���. �*���. �*���. �*���.

� ������ ������ ������ ����������������'�����������'�����������'�����������'� �*���.� �*���.� �*���.� �*���.

� �����:���� �����:���� �����:���� �����:��� �������'�������'�������'�������'���������������'�����������'�����������'�����������' �*���. �*���. �*���. �*���.

� ������ ������ ������ ������������7���'��������7���'��������7���'��������7���'�� �*���.� �*���.� �*���.� �*���.

� �����:���� �����:���� �����:���� �����:��� ���7���'����7���'����7���'����7���'������������7���'��������7���'��������7���'��������7���'� �*���. �*���. �*���. �*���.

� �����>������ �����>������ �����>������ �����>��������I����I����I����I�� �*���.� �*���.� �*���.� �*���.

� �����:���� �����:���� �����:���� �����:��� ���I����I����I����I��>�����>�����>�����>���� ���I����I����I����I� �*���. �*���. �*���. �*���.

....

Page 41: Intro to Software Engineering - Coding Standards

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

��!��#�#�������!��#�#�������!��#�#�������!��#�#�����6�����7 ��8�)�����6�����7 ��8�)�����6�����7 ��8�)�����6�����7 ��8�)���������� ��3�������������� ��3�������������� ��3�������������� ��3���������)����9!3�#�)����9!3�#�)����9!3�#�)����9!3�#� ����

��!��#�9!3�#���!��#�9!3�#���!��#�9!3�#���!��#�9!3�#� 8��:�'1����8��:�'1����8��:�'1����8��:�'1����������������

��!��#�9!3�#���!��#�9!3�#���!��#�9!3�#���!��#�9!3�#� 8��9� 1����8��9� 1����8��9� 1����8��9� 1����������������

��!��#�;����8��!��#�;����8��!��#�;����8��!��#�;����8 8��6�����7:���8��6�����7:���8��6�����7:���8��6�����7:���������������

����

• To register/deregister a property change listener, call:��!��#��� ���!��#��� ���!��#��� ���!��#��� �� 6�����7 ��8�<�������� 6�����7 ��8�<�������� 6�����7 ��8�<�������� 6�����7 ��8�<������� ����6�����7 ��8�<�������6�����7 ��8�<�������6�����7 ��8�<�������6�����7 ��8�<������� ������������

��!��#��� ���!��#��� ���!��#��� ���!��#��� ������6�����7 ��8�<������������6�����7 ��8�<������������6�����7 ��8�<������������6�����7 ��8�<������� ����6�����7 ��8�<�������6�����7 ��8�<�������6�����7 ��8�<�������6�����7 ��8�<������� ������������

• On the listener side, implement method:��!��#��� ��!��#��� ��!��#��� ��!��#��� 6�����7 ��8�6�����7 ��8�6�����7 ��8�6�����7 ��8�����6�����7 ��8�)����6�����7 ��8�)����6�����7 ��8�)����6�����7 ��8�)���� ������������������������

Constrained properties

• Changes and events are vetoable and reversible

Page 42: Intro to Software Engineering - Coding Standards

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

���������� ������� ������

Page 43: Intro to Software Engineering - Coding Standards

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 listenersNeed to implement an interface that extends java.beans.EventListenerHave a handler method for each event the listener listens to

�����������'���,5"���������?������3�:�� ���������������'���,5"���������?������3�:�� ���������������'���,5"���������?������3�:�� ���������������'���,5"���������?������3�:�� ����;:���"��������;:���"��������;:���"��������;:���"��������****

:�����'���,5� :�����'���,5� :�����'���,5� :�����'���,5�

....

• Event sourcesProvide pairs of register and unregister methods

� �����:��������'���,5"���������'���,5"��������� � �����:��������'���,5"���������'���,5"��������� � �����:��������'���,5"���������'���,5"��������� � �����:��������'���,5"���������'���,5"���������

� �����:��������:��'���,5"���������'���,5"��������� � �����:��������:��'���,5"���������'���,5"��������� � �����:��������:��'���,5"���������'���,5"��������� � �����:��������:��'���,5"���������'���,5"���������

• Event adaptersMerge event streamsBoth listener and sourceCan perform arbitrary filtering functions

Page 44: Intro to Software Engineering - Coding Standards

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 filesPossibly, several beans

• Serialized objects representing bean prototypes (instances)Contain state information (customization, field values)

• Optionally, a manifest fileContents of the archive

• Optional help files in HTML

• Optional localization information

• Resource files needed by the beanIconsGIF, JPEG, ...

Page 45: Intro to Software Engineering - Coding Standards

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...

Page 46: Intro to Software Engineering - Coding Standards

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 codeDocumentation should be modular, just like code

• Avoid: redundant, repetitious textInvites consistency problems whenever changes are madeGood: say something in one place, insert cross-reference in the other place“Window envelope” principleRedundancy is useful in some situations, but it better have a good excuse

Support cross-checksSupport quick high-level view

• Avoid: amalgamated textGood: isolate ideas, keep each sentence focused, summarize each paragraph in the opening sentence

• Avoid: update help files and user manuals independentlyGood: obtain manuals automatically from help files, or obtain both from code (e.g. by javadoc)Good: or, obtain both manually from the specification documents

Page 47: Intro to Software Engineering - Coding Standards

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 documentGood: rationale for your design decisions

Navigability!

• How easy is it to find the relevant information?

• Bad: unstructured textGood: table of contents, cross-references, hyperlinks, index of terms

Consistency!

• Consistent style facilitates information retrievalUnlike literary writing, technical writing is not made better by style variation

Clarity!

• E.g. avoid ambiguous expressions: “it”, “this”, ...

Page 48: Intro to Software Engineering - Coding Standards

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 conventionsftp://ftp.javasoft.com/docs/codeconv/CodeConventions.pdf

Java Beanshttp://java.sun.com/products/javabeans/

C coding conventionshttp://www.cs.mcgill.ca/resourcepages/indian-hill.html

Javadochttp://java.sun.com/products/jdk/javadoc/writingdoccomments.html

iContract toolshttp://www.reliable-systems.com/tools/iContract/iContract.htm