README.md 8.36 KB
Newer Older
Praetorius, Simon's avatar
Praetorius, Simon committed
1
# Scientific Programming with C++
Praetorius, Simon's avatar
Praetorius, Simon committed
2
In this module SCPROG the exercises and projects will be submitted online into a version
Praetorius, Simon's avatar
Praetorius, Simon committed
3
4
5
6
7
8
9
10
11
12
control system [Git](https://git-scm.com/) hosted at the MatNat [GitLab](https://gitlab.mn.tu-dresden.de)
platform, which is a web-based Git repository manager similar to [GitHub](https://github.com) 
and [Bitbucket](https://bitbucket.org).

Handing in solutions to exercises and projects digitally on such a platform is a 
good way of learning and training collaborative coding, which is commonplace in 
Scientific Computing research groups.

In order to allow fast correction and evaluation of submitted solutions, we require
a predefined structure of the repositories and coding styles to be follwed. Not
Praetorius, Simon's avatar
Praetorius, Simon committed
13
following these rules for repositories may result in your solution not being reviewed.
Praetorius, Simon's avatar
Praetorius, Simon committed
14
15
16
17
18
19
20
You will then have to reformat it and submit again. Not following the style guidelines
may result in point deduction, with the amount of points depending on the impact your
style could have on actual collaborative projects.

# Your Repository on GitLab
## Account
In the first tutorial we will create an account on the local GitLab platform, 
Praetorius, Simon's avatar
Praetorius, Simon committed
21
22
using the ZIH-Login (s...-number) for the account user name associated to your TU-Dresden
email address. This ensures that you will get credit for your submissions.
Praetorius, Simon's avatar
Praetorius, Simon committed
23
24
25

## Project Name
Please form groups of up to three members and exchange contact details so you can find
Praetorius, Simon's avatar
Praetorius, Simon committed
26
27
28
each other on GitLab. One of you should create a *private* (!) project, and invite the rest
of the group. The name of your project is `scprog-Name1Name2Name3`, where `Name1`
is the last name of the first student, `Name2` that of the second student, and so on. These
Praetorius, Simon's avatar
Praetorius, Simon committed
29
30
31
32
33
34
35
36
37
38
names should be sorted alphabetically. If your lineup changes for any reason during the
course of the semester, please create a new project that reflects this and inform your
tutors.

## Directory Structure
Your repository should consist of two levels of directories, one for the exercise sheets and
one for the individual exercises. This results in a tree structure like this:

```
sheet1
Praetorius, Simon's avatar
Praetorius, Simon committed
39
40
41
42
43
44
45
46
47
48
 +-- exercise1
 |    +-- main.cc
 |    +-- solution.txt
 |    \-- <header and source files>
 |
 +-- exercise2
 |    \-- <files as above>
 |
 \-- (...)
 
Praetorius, Simon's avatar
Praetorius, Simon committed
49
sheet2
Praetorius, Simon's avatar
Praetorius, Simon committed
50
51
52
53
54
 +-- exercise1
 +-- exercise2
 \-- (...)
 
(...)
Praetorius, Simon's avatar
Praetorius, Simon committed
55
56
57
58
59
60
61
```

You are free to name and structure your C++ files in any way you like, but there
should always be a file named `main.cc` that is a sample application of your implemented
classes. Often the content is given in the exercise, if it isn’t you are free to choose
sensible test cases yourselves. Make sure that this file `main.cc` can be compiled with
the command given in the lecture, or alternatively provide a [MakeFile](http://www.c-howto.de/tutorial/makefiles/) 
Praetorius, Simon's avatar
Praetorius, Simon committed
62
or [CMakeLists.txt](https://cmake.org/cmake/help/latest/) that builds the exercise.
Praetorius, Simon's avatar
Praetorius, Simon committed
63
64
65

The file `solution.txt` is meant for the output of your `main.cc` and for answering
questions that appear in the exercises. If an exercise is of theoretical nature and doesn’t
Praetorius, Simon's avatar
Praetorius, Simon committed
66
67
68
include actual coding, this is the only file you have to submit. Optionally you can
submit a [Markdown](https://docs.gitlab.com/ee/user/markdown.html) file `solution.md`
instead. This allows basic formatting of the text.
Praetorius, Simon's avatar
Praetorius, Simon committed
69
70

## Access to the Repository
Praetorius, Simon's avatar
Praetorius, Simon committed
71
Please give your tutor @spraetor write access to your project so that your submissions can be
Praetorius, Simon's avatar
Praetorius, Simon committed
72
73
74
75
graded. You also need to give read access to the repository to all tutors if there is
more than one, regardless of the group you are in. This allows for flexible handling of
unforeseen situations.

Praetorius, Simon's avatar
Praetorius, Simon committed
76
# Submission of Exercises
Praetorius, Simon's avatar
Praetorius, Simon committed
77
On each exercise sheet some exercises are marked for submission. You have approximately 
Praetorius, Simon's avatar
Praetorius, Simon committed
78
two weeks for each of these exercises, where the final date is written next to the exercise. 
Praetorius, Simon's avatar
Praetorius, Simon committed
79
In order to get your solutions reviewed, it has to be commited to your GitLab repository 
Praetorius, Simon's avatar
Praetorius, Simon committed
80
81
82
83
84
following the procedure:

1. For each exercise sheet create a new branch called `sheetX` where `X` is the number of
   the sheet.
2. Create the new directory following the directory structure as above
Praetorius, Simon's avatar
Praetorius, Simon committed
85
3. Commit your solutions to the branch
Praetorius, Simon's avatar
Praetorius, Simon committed
86
87
88
89
90
4. Create a merge request to your master branch

After final review of your submission (and maybe inclusion of your corrections) 
you get a :thumbsup: and can merge your branch into your `master` branch.

Praetorius, Simon's avatar
Praetorius, Simon committed
91
92
**Note:** each member of the group should participate in the submission, i.e. 
commit her/his contributions individually and not just by the creator of the 
Praetorius, Simon's avatar
Praetorius, Simon committed
93
repository, if the exercise amount allows for splitting.
Praetorius, Simon's avatar
Praetorius, Simon committed
94

Praetorius, Simon's avatar
Praetorius, Simon committed
95
96
97
98
99
100
101
102
103
104
105
# Style Guidelines
All programs you submit should follow basic programming rules like the following:

- **Formatting**
  - Put each instruction on a separate line (two lines if it is very large)
  - Use spaces to separate variable names, functions and operators
  - Indent your lines to visually mark different lines belonging to different scopes
- **Variable names**
  - The name should reflect the purpose of the variable
  - Variable names start with a lowercase letter, types with an uppercase letter
  - The rest of the name format for identifiers is up to you
Praetorius, Simon's avatar
Praetorius, Simon committed
106
  - Simple counting integers and similar variables are exempt
Praetorius, Simon's avatar
Praetorius, Simon committed
107
108
109
110
111
112
113
114
115
116
117
- **Comments**
  - Comments allow others to understand your intentions
  - Tutors can only give you points if they understand what you were trying to do
  - *Guideline:* one comment per class, per function, per algorithm subtask, per tricky or "exotic" source line
  - Don’t comment to much either, this may visually drown the actual code or diverge from what is actually coded (!)
  - Leave out trivial comments ("This is the constructor")
- **Language constructs**
  - You may use any construct you want, even if it has not yet been introduced in the lecture
  - Avoid constructs that have been superseded by better alternatives in the lecture
  - Declare variables and references as const where it is possible
  - Separate interface and implementation by correctly using public and private
Praetorius, Simon's avatar
Praetorius, Simon committed
118
119
120
  - Use exceptions instead of asserts / aborts and smart pointers instead of raw pointers once the lecture has introduced them

See [Google C++ Style Guide](http://google.github.io/styleguide/cppguide.html) for 
Praetorius, Simon's avatar
Praetorius, Simon committed
121
more rules and guidelines on the coding style. Also, see the 
Praetorius, Simon's avatar
Praetorius, Simon committed
122
[C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) 
Praetorius, Simon's avatar
Praetorius, Simon committed
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
for a comprehensive list of best practice programming rules for C++.

# More reading
Online references and literature useful for completing the exercises are listed below:

- **Online-References:** 
  - [cppreference.com](http://en.cppreference.com), [BLAS](http://www.netlib.org/blas), 
    [LAPACK](http://www.netlib.org/lapack/), [DUNE](https://www.dune-project.org/doxygen/), 
    [Git](https://git-scm.com/docs), [Boost](https://www.boost.org/doc/libs/1_71_0/), 
    [CMake](https://cmake.org/cmake/help/latest/)
- **Cheetsheets:** 
  - [Divhints](https://devhints.io/), [Git](https://github.github.com/training-kit/downloads/github-git-cheat-sheet.pdf), 
    [Linux Command Line](https://appletree.or.kr/quick_reference_cards/Unix-Linux/Linux%20Command%20Line%20Cheat%20Sheet.pdf)
- **Tutorials:** 
  - [MTL4](http://old.simunova.com/docs/mtl4/html/tutorial.html), [Git](https://git-scm.com/book/en/v2)
- **Compiler:** 
  - [GCC](https://gcc.gnu.org/), [Clang](http://clang.llvm.org/), [Intel Icc](https://software.intel.com/en-us/c-compilers)
- **Books:** 
  - Discovering Modern C++: An Intensive Course for Scientists, Engineers, and Programmers, Peter Gottschling, 2015: 
    [slub](http://katalogbeta.slub-dresden.de/id/0017278767/#detail), [online](http://proquest.tech.safaribooksonline.de/9780134383682)
  - *References:* Die C++ Programmiersprache (Bjarne Stroustrup), 
    C++ Kurz & Gut (Kyle Loudon, Rainer Grimm): [slub](http://katalogbeta.slub-dresden.de/id/0012713756/#detail)
  - *Beginners:* C++ Primer (Stanley Lippman, Josee Lajoie, Barbara E. Moo): [online](http://proquest.tech.safaribooksonline.de/9780133053043)
  - *Intermediate level:* Effective Modern C++ (Scott Meyers): [slub](http://katalogbeta.slub-dresden.de/id/0013617247/#detail), [online](http://proquest.tech.safaribooksonline.de/9781491908419), 
    C++ Templates: The Complete Guide (David Vandevoorde, Nicolai M. Josuttis): [online](http://proquest.tech.safaribooksonline.de/0201734842)
  - *Experts:* Modern C++ Design (Andrei Alexandrescu): [online](http://proquest.tech.safaribooksonline.de/0201704315), 
    C++ Template Metaprogramming (David Abrahams, Aleksey Gurovoy): [online](http://proquest.tech.safaribooksonline.de/0321227255)