Coding standards
McGill ECSE 321Introduction to Software Engineering
Radu Negulescu
Fall 2003
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
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”]
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
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
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
�������������������� ��������������������������������� ��������������������������������� ��������������������������������� �������������
����������� ����������� ��������������������� ����������� ��������������������� ����������� ��������������������� ����������� ����������
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)
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
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
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
�����&�����&�����&�����& ��)�� ��)�� ��)�� ��)��
�'���(�)�(����(�'���(�)�(����(�'���(�)�(����(�'���(�)�(����( ������������������������)��� �����������(����������)��� �����������(����������)��� �����������(����������)��� �����������(��
****
������������
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?
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:
�������������������������������������������� ���� ���� �� ���� ���� ���� ������
����
��������������������������������������������
��������������������������������������������
������������
����
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
�'���(��������� �����������'���(��������� �����������'���(��������� �����������'���(��������� ����������
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�� �*
�����������'��������������'��������������'��������������'���
....
....
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
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
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?
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
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”
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
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
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
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)
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
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)
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]”
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��������& �*
������������
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
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������������,�
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
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��������& �*
������������
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,�����,����#� ����������� �������� �������� �������� ������������������.(�.(�.(�.(�,,,,,,,,������������������������������,���� �#���� �����,���� �#���� �����,���� �#���� �����,���� �#���� ��� ����������������.(�.(�.(�.(�,,,,,,,,�����������������������������������$��%���*�������$��%���*�������$��%���*�������$��%���*
�������������������������������� ����
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
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
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
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
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”
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
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
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� �*���. �*���. �*���. �*���.
....
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
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
���������� ������� ������
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
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, ...
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...
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
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”, ...
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