Establishing stylistic conventions #13

New Issue

glyph · 2021-11-02T12:11:26Z

glyph commented

2021-11-02 12:11:26 +00:00

I'm currently reviewing the web routes refactor PR and think it might be useful to agree on some comment conventions. My goal is to have consistency without too much rigidity.

Here are some suggestions to start the conversation:

Doc comments (/// or !//) : the first word should be capitalised and each sentence should end with a full-stop. Example:

/// This function is publicly exposed for users who have forgotten their password.

Code comments (// or /* ... */) : all lowercase and without an ending full-stop. Example:

// check to see if there is a flash message to display

Code section header comments : I'm open to ideas here. Should ideally be eye-catching / easy to find. We could use a # (like you use in the refactor PR) to make the text bold; I use vim for coding and so it doesn't have an effect for me.

// ----------------------------- //
// HELPERS AND ROUTES FOR /login //
// ----------------------------- //

I think the first point is the one I care most about, since the doc comments are rendered into the 'official' Rust API documentation for our crates and are therefore more likely to be read by a wider audience. Code comments, on the other hand, will mostly only be read by us and future contributors. From the perspective of a contributor to established project: it has helped he in the past when I see an established convention in the code; then I simply replicate that style in my contributions.

Anywho, not a major thing but I figured it was good to chat about.

@notplants I'm currently reviewing the [web routes refactor PR](https://git.coopcloud.tech/PeachCloud/peach-workspace/pulls/12) and think it might be useful to agree on some comment conventions. My goal is to have consistency without too much rigidity. Here are some suggestions to start the conversation: 1. Doc comments (`///` or `!//`) : the first word should be capitalised and each sentence should end with a full-stop. Example: `/// This function is publicly exposed for users who have forgotten their password.` 2. Code comments (`//` or `/* ... */`) : all lowercase and without an ending full-stop. Example: `// check to see if there is a flash message to display` 3. Code section header comments : I'm open to ideas here. Should ideally be eye-catching / easy to find. We could use a `#` (like you use in the refactor PR) to make the text bold; I use vim for coding and so it doesn't have an effect for me. ``` // ----------------------------- // // HELPERS AND ROUTES FOR /login // // ----------------------------- // ``` ----- I think the first point is the one I care most about, since the doc comments are rendered into the 'official' Rust API documentation for our crates and are therefore more likely to be read by a wider audience. Code comments, on the other hand, will mostly only be read by us and future contributors. From the perspective of a contributor to established project: it has helped he in the past when I see an established convention in the code; then I simply replicate that style in my contributions. Anywho, not a major thing but I figured it was good to chat about.

glyph added the

documentation

label 2021-11-02 12:14:00 +00:00

glyph commented

2021-11-02 12:16:51 +00:00

Two other ones which come to mind:

Using TODO and FIX in code comments when appropriate (these are highlighted in yellow in my text editor, making them easy to spot).

Two other ones which come to mind: Using `TODO` and `FIX` in code comments when appropriate (these are highlighted in yellow in my text editor, making them easy to spot).

notplants commented

2021-11-02 12:26:42 +00:00

All points sounds good to me.

The third style, hmmm..
interestingly in my IDE, it only shows up bold when a # is used inside of /// (not a //).

Ideally would also like to avoid a pattern that is difficult to copy/paste, or where you need to manually edit the characters to make the pattern the correct "size". I don't love that as you type more characters, the stuff on the right side goes out of alignment and needs to be manually adjusted.

Maybe

// ---------------------------------------------------
// HELPERS AND ROUTES FOR /login/here/is/longer/route 
// ---------------------------------------------------

or other ideas?

I would also probably lean towards more smaller files, with the prefixes like delta, than doing lots of code sections, since its pretty easy to navigate around between files.

All points sounds good to me. The third style, hmmm.. interestingly in my IDE, it only shows up bold when a # is used inside of /// (not a //). Ideally would also like to avoid a pattern that is difficult to copy/paste, or where you need to manually edit the characters to make the pattern the correct "size". I don't love that as you type more characters, the stuff on the right side goes out of alignment and needs to be manually adjusted. Maybe ``` // --------------------------------------------------- // HELPERS AND ROUTES FOR /login/here/is/longer/route // --------------------------------------------------- ``` or other ideas? I would also probably lean towards more smaller files, with the prefixes like delta, than doing lots of code sections, since its pretty easy to navigate around between files.

glyph commented

2021-11-03 08:52:47 +00:00

interestingly in my IDE, it only shows up bold when a # is used inside of /// (not a //).

Huh, that is interesting. Was just thinking about it and I believe it does that because markdown can be included in doc comments so that it's formatted when the docs are generated. That would explain why it doesn't do the bolding with //.

Ideally would also like to avoid a pattern that is difficult to copy/paste, or where you need to manually edit the characters to make the pattern the correct "size". I don't love that as you type more characters, the stuff on the right side goes out of alignment and needs to be manually adjusted.

With this in mind, perhaps we could drop the dashes completely? Like this:

//
// HELPERS AND ROUTES FOR /login/here/is/longer/route 
//

I would also probably lean towards more smaller files, with the prefixes like delta, than doing lots of code sections, since its pretty easy to navigate around between files.

Yeahh this would make the section headings redundant. My vote would be to stick with section headers for now and then we can evaluate the splitting at a later stage. Would definitely make a lot of sense for the big files. I'm happy we're having these kinds of higher-level discussions.

The classic problem of lumping versus splitting 😆

> interestingly in my IDE, it only shows up bold when a # is used inside of /// (not a //). Huh, that is interesting. Was just thinking about it and I believe it does that because markdown can be included in doc comments so that it's formatted when the docs are generated. That would explain why it doesn't do the bolding with `//`. > Ideally would also like to avoid a pattern that is difficult to copy/paste, or where you need to manually edit the characters to make the pattern the correct "size". I don't love that as you type more characters, the stuff on the right side goes out of alignment and needs to be manually adjusted. With this in mind, perhaps we could drop the dashes completely? Like this: ``` // // HELPERS AND ROUTES FOR /login/here/is/longer/route // ``` > I would also probably lean towards more smaller files, with the prefixes like delta, than doing lots of code sections, since its pretty easy to navigate around between files. Yeahh this would make the section headings redundant. My vote would be to stick with section headers for now and then we can evaluate the splitting at a later stage. Would definitely make a lot of sense for the big files. I'm happy we're having these kinds of higher-level discussions. The classic problem of lumping versus splitting 😆

glyph commented

2021-11-03 09:09:01 +00:00

Even simpler (I just noticed that I had already been using this pattern):

Just use all-caps for section headings:

// HELPERS AND ROUTES FOR /login/here/is/longer/route

// this function does a thing
fn thing_doer() {
    thing();
}

Even simpler (I just noticed that I had already been using this pattern): Just use all-caps for section headings: ```rust // HELPERS AND ROUTES FOR /login/here/is/longer/route // this function does a thing fn thing_doer() { thing(); } ```

Sign in to join this conversation.