Defects vs subsets #127
Defects vs subsets #127
Conversation
…n explicit Amplification section exists (instead, whatever paragraph immediately opens the guideline is just normative). We can continue to call it that but the subheading is not necessary.
Co-authored-by: Pete LeVasseur <plevasseur@gmail.com>
✅ Deploy Preview for scrc-coding-guidelines ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Thanks @AlexCeleste for the excellent additions! Could you take a look at the comments I left?
By the way -- I think I recall you saying the plan is to incorporate these examples more into the Style Guideline to help flesh it out. Was that right? In this PR or another?
I suppose then it would be quite helpful to use the examples to illustrate the difference between a defect and subset.
| @@ -99,6 +99,10 @@ | |||
| dict(name="readability", description="Readability-related guideline"), | |||
| dict(name="reduce-human-error", description="Reducing human error guideline"), | |||
| dict(name="numerics", description="Numerics-related guideline"), | |||
| dict(name="undefined-behavior", description="Numerics-related guideline"), | |||
|
|
|||
| dict(name="defect", description="Guideline associated with the language-subset profile"), | |||
There was a problem hiding this comment.
If you'd like we can have a new Sphinx Needs option for whether it's a defect or subset.
If we think most guidelines can or should be classified as one or the other it might make sense.
What do you think?
There was a problem hiding this comment.
Created an issue for this, perhaps we tackle this later:
#142
What do you think @AlexCeleste?
| @@ -308,15 +304,27 @@ what it covers. | |||
| Content **SHOULD** aim to be as short and self-contained as possible, while still explaining | |||
| the scope of the guideline. | |||
|
|
|||
| Content **SHOULD NOT** cover the rationale for the guideline, which is done in the ``rationale`` section. | |||
There was a problem hiding this comment.
I think you mentioned about removing the IETF RFC 2119-styling to this chapter when it was intended for readers. Now that it's intended for contributors are you thinking to keep it in?
Or is this change unrelated to that to aid in understanding?
There was a problem hiding this comment.
Perhaps this was rewritten in order to read better? Curious to hear your thoughts.
PLeVasseur
added this to the
Get some initial coding guidelines landed, get a sense of any challenges milestone
There was a problem hiding this comment.
Left a couple of thoughts! Thanks a bunch for sweeping through and addressing comments @AlexCeleste
| @@ -99,6 +99,10 @@ | |||
| dict(name="readability", description="Readability-related guideline"), | |||
| dict(name="reduce-human-error", description="Reducing human error guideline"), | |||
| dict(name="numerics", description="Numerics-related guideline"), | |||
| dict(name="undefined-behavior", description="Numerics-related guideline"), | |||
|
|
|||
| dict(name="defect", description="Guideline associated with the language-subset profile"), | |||
There was a problem hiding this comment.
Created an issue for this, perhaps we tackle this later:
#142
What do you think @AlexCeleste?
| @@ -308,15 +304,27 @@ what it covers. | |||
| Content **SHOULD** aim to be as short and self-contained as possible, while still explaining | |||
| the scope of the guideline. | |||
|
|
|||
| Content **SHOULD NOT** cover the rationale for the guideline, which is done in the ``rationale`` section. | |||
There was a problem hiding this comment.
Perhaps this was rewritten in order to read better? Curious to hear your thoughts.
| originally performed in a differently-sized address space. | ||
|
|
||
| While ``as`` can notionally be used to create a null pointer, the functions | ||
| ``core::ptr::null`` and ``core::ptr::null_mut`` are the more idiomatic way to do this. |
There was a problem hiding this comment.
I was reading the documentation of the Sphinx coding guidelines extension (again, shamelessly taken from the FLS) and we should also be able to use it with items from core, e.g.
| ``core::ptr::null`` and ``core::ptr::null_mut`` are the more idiomatic way to do this. | |
| :std:`core::ptr::null` and :std:`core::ptr::null_mut` are the more idiomatic way to do this. |
(note the single ticks instead of double ticks)
This adds a basic example of three kinds of guideline: