csci 1060u lecture 01 - code style & documentation i€¦ · csci 1060u programming workshop!...

CSCI 1060U Programming Workshop

§  Professor: Dr. Jeremy S. Bradbury §  Phone: 905-‐721-‐8668 ext. 3685 §  E-‐mail: [email protected] §  Office hour: To be announced (UA4016),

otherwise by appointment §  Teaching Assistants:

Michael Miljanovic §  E-‐mail: [email protected] §  Office hour: during labs (J123A),

otherwise by appointment

© J.S. Bradbury CSCI 1060U Lecture 1 Slide 1


§  Lectures: §  Tues. 12:40pm – 2:00pm (UA1220) §  Thur. 11:10am – 12:30pm (UA1220)

§  Laboratories: §  Wed. 11:10am – 2:00am (J123A) §  Thurs. 12:40pm – 3:30pm (J123A)

© J.S. Bradbury

Note: •  labs start next week.

CSCI 1060U Lecture 1 Slide 2


§  Aims of the Course: §  The primary purpose of this course is to provide a

strong foundation for programming practices and theory.

§  This course will focus on object-oriented programming in C++.



§  Textbook: §  Bjarne Stroustrup, A

Tour of C++ § This book will be the

primary course reference and is a good general C++ reference.



§  Textbook: §  Online Resources.

§ Online articles and websites will be used to supplement the textbooks. Links to all online resources will be posted in the course website on WebCT.



§  Topics (include but are not limited to): §  Program Documentation §  Code Style & Program Refactoring §  Program Debugging Techniques & Assertions §  Advanced C++ (recursion, pointers and more…) §  Object-Oriented Design (inheritance, polymorphism,

and more…) §  Templates & the Standard Template Library



§  Marking:

Laboratories (weekly) 40%

Term Tests (2) 20%

Final Exam 40%


Note: The schedule for tests is as follows: •  Test #1 – Thursday, Feb. 26, 2015 •  Test #2 – Tuesday, Apr. 7, 2015


§  Laboratories §  This course will have weekly laboratories. §  Laboratories will allow students to practice the

programming concepts and techniques that are covered in the lectures.

§  All labs will be done individually §  Each lab may include in-lab and take-home problems.

§  Laboratory Submissions §  Unless otherwise specified in the instructions, all

laboratory work should be submitted using Blackboard.


Code Style & Documentation I

Overview §  The style of your code and the program documentation

both have a significant affect on the readability, maintainability and testability of your programs

§  Today we will look at: §  appropriate code style for C++ (and Java) §  program documentation guidelines for C++ (and Java)


© J.S. Bradbury

In Class Activity: Using C++ write a commented program that can take an array of characters and identify the first character that appears only once in the array. The input for the program should be a: a b d r f g f r d a g … The output for the program should be: b If there is no character that appears only once the output should be: no instance found


Program Style

Indentation & White Space §  Can be used to help group lines of code §  Some general rules include:

1.  Insert a blank line between distinct sections of statements

2.  Indent statements that are within another statement (e.g., inside an if statement or a while statement)

3.  Place closing braces on a distinct line. Place opening braces on a distinct line or at the end of the preceding line.


Program Style

Line Length §  In C++ it is usually advised to avoid lines that are

longer than 80 characters. §  Why?

§  Improved readability in terminals §  Typically avoids bad wrapping by printers §  …

© J.S. Bradbury

What happens if our line is more than 80 characters? Need to wrap text!


Program Style

Line Length §  The following Java wrapping guidelines also work for

C++: §  “Break after a comma. §  Break before an operator. §  Prefer higher-level breaks to lower-level breaks. §  Align the new line with the beginning of the expression at

the same level on the previous line. §  If the above rules lead to confusing code or to code that's

squished up against the right margin, just indent 8 spaces instead.” 1

© J.S. Bradbury

1Source of guidelines is http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html


Program Style

Comments §  Comments are used in a program to increase the

readability of the code §  Reasons for using comments include:

§  Explanations of statements §  Description of usage of statements §  Etc.

§  (We will learn more about comments when we talk about documentation)


Program Style

Comments §  In C++ comments can occur in two ways:

© J.S. Bradbury

// everything from start symbol to the end of line // is a comment

/* Everything between the start and end symbols is a comment. */

or


Program Style

Naming Conventions §  In C++ there are general naming conventions for

variables, constants and functions §  also for namespaces, etc.

§  A company or a project may also have specific naming conventions


Program Style

C++ Naming Conventions

© J.S. Bradbury

Identifier Type

Rules for Naming Examples

File Names “…should be all lowercase and can include underscores (_) or dashes (-)”

a_file.cpp

Type Names

“…start with a capital letter and have a capital letter for each new word, with no underscores…” Types should be nouns.

MyClass

Variable Names

“…all lowercase, with underscores between words. Class member variables have trailing underscores.” Variables should be nouns.

local_variable member_variable_

Constant Names

“Use a k followed by mixed case” kMyConstant

Function Names

“Regular functions have mixed case” MyFunction();

Source: This table is based on the website http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#General_Naming_Rules


Program Style

Java Naming Conventions

© J.S. Bradbury

Identifier Type


Packages “The prefix of a unique package name is always written in all-lowercase ASCII letters and should be one of the top-level domain names, currently com, edu, gov, mil, net, org, or one of the English two-letter codes identifying countries … Subsequent components of the package name vary…”

com.blah

Classes, Interfaces

“…should be nouns, in mixed case with the first letter of each internal word capitalized. Try to keep your class names simple and descriptive."

Class MyClass; Interface MyInterface;

Methods “Methods should be verbs, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized.”

myMethod(); Method(); myLongMethod();

Source: This table is modified from the table at: http://www.oracle.com/technetwork/java/codeconventions-135099.html


Program Style

Java Naming Conventions

© J.S. Bradbury

Identifier Type


Variables “Except for variables, all instance, class, and class constants are in mixed case with a lowercase first letter. Internal words start with capital letters. Variable names should not start with underscore _ or dollar sign $ characters…Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.“

int I; int size; int mySize;

Constants “…should be all uppercase with words separated by underscores ("_")”

static final int A_CNST=1;

Source: This table is modified from the table at: http://www.oracle.com/technetwork/java/codeconventions-135099.html


Program Style

File Structure §  Most programs will have many source files §  The organization of these files is also part of the

program style §  In Java, the use of packages defines directory

structure. §  In C++, the programmer has to decide on the

appropriate directory structure (usually based on the conventions of the company or project)


Documentation

§  Comments are a form of in-program documentation

§  When to comment and when not to comment comes with experience – but there are some general rules!


Documentation

§  Rule 1: Comment at the beginning of the source file with the main method/function. These comments should include: §  the purpose of the program, §  how it should be executed, §  the expected input/output, §  the version number §  Any additional information that would be appropriate


Documentation

§  Rule 2: At the beginning of all files/classes provide comment about §  The copyright notice §  the author, §  revision history and §  a description of the class. §  Rule 2A: If functions or methods within a class have

dependencies regarding their usage you should document these as well.

© J.S. Bradbury

Example: a stack class should include comments such as a push has to occur before a pop.


Documentation

§  Rule 3 (C++): For the function declaration include comments regarding the usage of the function. For the function definition include comments such as an explanation of how the function works, any parameters and return values.

§  Rule 3 (Java): For each method include comments detailing the purpose of the method, how it works, any parameters and return values.


Documentation

§  Rule 4: Comment groups of statements the require explanation. These comments should be: §  Non-obvious §  Provide insight into subtleties in the algorithm §  Explain why the statements do what they do


Documentation

§  In-program documentation contained in the comments can also be used to generate other forms of documentation

§  Often documentation generation tools are used §  Why?

§  Rewriting the document could lead to inconsistency between external and in-program documents

§  Rewriting documents takes more time and resources

© J.S. Bradbury

Example: API documentation



Summary §  We’ve discussed guidelines for appropriate code style

and documentation Next time §  We will continue to talk about documentation by

discussing Javadoc and Doxygen §  We will also continue to talk about program style – in

particular bad programming practices and how to fix them using code refactoring



References §  Mozilla Developer Network Coding Style

https://developer.mozilla.org/En/Mozilla_Coding_Style_Guide §  Google C++ Style Guide §  http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml §  Code Conventions for the Java Programming Language

http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html


csci 1060u lecture 01 - code style & documentation i€¦ · csci 1060u programming workshop!...

Documents