[Investigate] Commenting convention #34

Closed fgardt closed 1 year ago

In GitLab by @mm1398 on Mar 7, 2023, 12:20

Documentation description

In order to ensure a pleasant quality of work, it is important that we agree on how to comment in a uniform way.

Additional context

In GitLab by @mm1398 on Mar 7, 2023, 12:27

Here are some conventions for commenting in Dart:

Use concise comments to explain the intention of a function, class, or variable.

// This function calculates the sum of two numbers.
int sum(int a, int b) {
return a + b;
}

Avoid unnecessary comments. If your code is self-explanatory, don't add comments that repeat the obvious code.
```
// Wrong:
int a = 1; // Initialize variable "a" to 1.
```

// Right: int a = 1;


3. Use comments to explain code that is not obvious or difficult to understand.

// This loop iterates over each element in the list and prints it to the console. for (var element in list) { print(element); }


4. Use comments to mark TODOs or issues that need to be fixed.

// TODO: Implement the "sort" function based on the length of the strings. void sort(List list) { // ... }

5. Use comments to comment out code that you temporarily don't use but may need later.

// This line is commented out and will not be executed. // int result = calculateResult();



By following these conventions, you can ensure that your code is well-commented and easily understandable for other developers.

In GitLab by @mm1398 on Mar 7, 2023, 12:28

created branch 34-investigate-commenting-convention to address this issue

In GitLab by @mm1398 on Mar 7, 2023, 12:34

To approve the convention add :heavy_check_mark: as reaction or if you don't approve, comment what you want to be changed.

In GitLab by @Merseleo on Mar 7, 2023, 17:05

Make use of "/* ... /" instead of "//" for formatted comments. Maybe provide examples like here too?!

In GitLab by @Slartibartfass2 on Mar 7, 2023, 17:22

We already agreed on how to write documentation for Dart by following the rules of Effective Dart, which has a detailed description about documentation: Effective Dart: Documentation

In GitLab by @mm1398 on Mar 11, 2023, 10:56

unassigned @fgardt and @Shiroen95

In GitLab by @Merseleo on Mar 11, 2023, 22:42

So my proposal: @mm1398 adds a section / page in the Wiki about how we comment or at least what we use as an orientation. This section should mainly consist of links, how to comment on the different platforms, so

If you have the motivation, you could select the most important rules and list them. Furthermore, we could add a tick box to the MR template, so the reviewer need to look to the page and check, whether the comments conform the rules and if so, tick the box

In GitLab by @Slartibartfass2 on Mar 12, 2023, 14:49

Again I'm not sure why we need this. We agreed on a convention for each language that defines rules for commenting/documentation.

The Swift commenting section is a bit short. My proposal is to either add additional documentation rules or choose another convention that can be enforced by a linter. I don't see a point in adding further information for Dart and Kotlin.

In GitLab by @mm1398 on Mar 13, 2023, 10:01

When did we discuss this? I haven't found anything in the wiki. The idea behind the issue is that I would like to write it in the wiki and accordingly have your feedback on my proposal.

In GitLab by @mm1398 on Mar 13, 2023, 10:01

Sounds good!

In GitLab by @Slartibartfass2 on Mar 13, 2023, 10:22

This was part of the convention ticket several months ago. Each convention has a section about documentation, so I don't think we need additional information about that. (Except ios, see above)

In GitLab by @Merseleo on Mar 13, 2023, 12:53

The point is (as fair as I understand, @mm1398 sees this to): the convention links are not very clearly, so it could be useful to provide either a separate link (yes this would mean, which have to links to the documentation, but who cares) or summarize the rules. Because i don't scroll through the entire convention list every time I review something or write comments, but instead search for certain sections or examples.

In GitLab by @Slartibartfass2 on Mar 13, 2023, 18:45

I see, this would work for me.

Who does the job? @mm1398 ?

In GitLab by @mm1398 on Mar 14, 2023, 08:21

I would like to do it

In GitLab by @mm1398 on Mar 14, 2023, 08:41

created branch 34-investigate-commenting-convention-2 to address this issue

In GitLab by @mm1398 on Mar 14, 2023, 10:27

created branch docs/34-investigate-commenting-convention to address this issue

In GitLab by @mm1398 on Mar 14, 2023, 10:48

I have now summarized the convention in the wiki and updated the MR. You can check them in the wiki and also approve my MR.

In GitLab by @Slartibartfass2 on Mar 14, 2023, 11:40

LGTM.

The text in the wiki is indented which looks a bit odd imo, I think it's fine if it has the same indentation as the rest.

In GitLab by @Slartibartfass2 on Mar 14, 2023, 11:43

Also the formatting is sometimes wrong, e.g.

BAD
class RadioButtonWidget extends Widget {
/// Sets the tooltip for this radio button widget to the list of strings in
/// [lines].
void tooltip(List<String> lines) {
    ...
    }
}

it would look a bit better if the formatting is correct

uulm-smart-sensing / documentation