ASWI - Pokročilé softwarové inženýrství » ASWI 2021 » OpenData vlastní téma (KIV) - Tři Mušketýři

h1. Conventions and Guidelines (WIP)

h2. Issue Management

h3. Issue Trackers

This section explains, which tracker should be used for which type of issue.

* *Bug*

Use this tracker when the issue references a known bug that needs to be fixed.

* *Enhancement*

???

* *Task*

Use this tracker for issues related to implementation of a designed/analyzed part of the system.

* *Support*

Use this tracker for issues related to non-implementation task, e.g. any meeting issues, wiki editing, ...

* *Feature*

???

h3. Logging Time

When logging time for an issue, you should write a short comment, unless the subject of the issue is self-explanatory and the issue is going to be resolved, after you log the time, e.g. logging time for meetings.?

h4. Activity for Time Logging

* *Unspecified*

Do not use this activity.

* *Analysis*

Use this activity, when you're logging time for anything analytical, for example research/interface design/... ???

* *Design*

???

* *Implementation*

Use this activity, when you're logging time for implementing (coding) anything

* *Verification*

???

* *Documentation*

Use this activity, when you're logging time for creating/editing some documentation for exaplmple in some wiki page(s)

* *Administrative*

Use this activity for meetings

If the work you did matches more than one of the activities, either log time separately or choose such activity you spent most time doing.

h2. Code Contributions (Commits)

h3. Linking Commits to Issues

Every commit must be linked to an issue, i.e. in each commit use the key word *Re #<issue-no>*. Alternatively, you can use the key word *refs #<issue1-no>, #<issue2-no>*, although it is preferable for each commit to be linked with exaclty one issue.

If you think your commit is not related to any existing issue, link it to the "Refactoring" issue (such issue will be prepared for every iteration).

It is preferable for the keyword(s) to appear at the very beginning of a commit message.

You can use other keywords for referencing issues in commit messages, e.g. *closes, fixes, done, fixed* - these keywords also affect the issue itself. It is not required to use these keywords.

Note.: The keywords are caseinsensitive and at least one blankspace or colon is needed between the keyword and the first hash to produce a match (taken from Redmine doc).

h3. Commit messages

Every commit must have a commit message briefly explaining what the changes in the commit do.

h3. End of Iteration Tags

????

h2. Coding and Code Documentation

When coding, use the generally known best practices (whether they concern the used language or not), see some of the coding conventions for C# at https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions.

h3. General Naming Conventions

https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/general-naming-conventions

Choose easily readable identifier names

Favor readability over brevity

Do not use underscores, hyphens, or any other nonalphanumeric characters

h3. Capitalization Conventions

https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/capitalization-conventions

Use PascalCasing (i.e. camelCasing with the first character capitalized) for naming the following types of identifiers:

* Namespace

* Type

* Interface

* Method

* Property

* Event

* Field

* Enum value

Use camelCasing for parameters

h3. Code Commenting

Use documentation comments for classes and methods (see https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/documentation-comments)

Use in-code comments too - the rules for this aren't strict, but try to comment every line/block of code, which might be even a little unclear to the reader

Sign each file you create (at the beginning of the file add a comment with the following line): "Author: Your Name"

h2. Wiki Documentation

On the wiki main page, you can find links to most of the important pages related to the project.

On some of the pages, the links to child pages appear in the text - if you struggle to find anything, go to *Index by title* and find the page you are looking for there.

Write/edit pages in English.