Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update guideline for comments for interface implementation. #15

Merged
merged 4 commits into from
Mar 18, 2020

Conversation

Gilthoniel
Copy link
Contributor

No description provided.

@Gilthoniel Gilthoniel requested a review from nkcr March 18, 2020 07:21
@Gilthoniel Gilthoniel self-assigned this Mar 18, 2020
@nkcr
Copy link
Contributor

nkcr commented Mar 18, 2020

For the record, we went through many possibilities:

// Stream belongs to the mino.RPC implementation
// Stream implements mino.RPC.Stream
// Stream implements mino.RPC.Stream()
// Stream implements mino.RPC
// Stream contributes to mino.RPC
// Stream contributes to implementing mino.RPC
// Stream belongs to the mino.RPC interface
// Stream is an element of the mino.RPC interface
// Stream is a member of mino.RPC
// Stream belongs to mino.RPC
// Stream belongs to interface mino.RPC
// Stream belongs to mino.RPC interface

And we choose to favour a concise and easy to remember phrasing with // Stream implements mino.RPC even if that may not be a 100% technically true. We believe it is better to have simple rules that are followed instead of complex ones that we don't use.
Some discussion here #13 (comment).

@Gilthoniel Gilthoniel added the R4M 🚀 The PR is ready to be reviewed and merged label Mar 18, 2020
docs/guideline.md Outdated Show resolved Hide resolved
Co-Authored-By: Noémien Kocher <nkcr.je@gmail.com>

func TestDummy_String(t *testing.T) {}
```

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add something to handle more complex situation, like:

For some situation, it is necessary to add detailed information about a test case. This can be done between the SCOPE and the FUNCTION:

func Test_RPC_MultipleSimple_Stream(t *testing.T) {
...
}

As an invariant, the SCOPE and FUNCTION should always be the first, respectively the last, element.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

@nkcr nkcr merged commit 45da0ad into master Mar 18, 2020
@nkcr nkcr deleted the doc_guideline branch March 18, 2020 09:46
bbjubjub2494 pushed a commit to bbjubjub2494/dela that referenced this pull request Aug 3, 2024
Update guideline for comments for interface implementation.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
R4M 🚀 The PR is ready to be reviewed and merged
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants