Skip to content

Commit

Permalink
Modify rule: Update rule descriptions (#3655)
Browse files Browse the repository at this point in the history
Changes suggested by the Docs Squad:

* Modify rule s2178: Update rule description
- formalize word selection to clarify the description

* Modify rule S2551: capitalize `String`
- follow the capitalization of a proper noun, in accordance with the referenced link

* Modify rule S3923: improve word choice

* Modify rule S2551: capitalize String
- `String` is used as a VB `object` in this example. 
- A new PR will be issued to make a more substantial improvement
  • Loading branch information
kevin-hinz authored Feb 23, 2024
1 parent cfa09e0 commit a46b16a
Show file tree
Hide file tree
Showing 3 changed files with 4 additions and 4 deletions.
2 changes: 1 addition & 1 deletion rules/S2551/vbnet/rule.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ The following objects are considered as shared resources:

* a reference to https://learn.microsoft.com/en-us/dotnet/visual-basic/programming-guide/program-structure/me-my-mybase-and-myclass#me[Me]: if the instance is publicly accessible, the lock might be shared
* a https://learn.microsoft.com/en-us/dotnet/api/system.type[Type] object: if the type class is publicly accessible, the lock might be shared
* a https://learn.microsoft.com/en-us/dotnet/visual-basic/language-reference/data-types/string-data-type[string] literal or instance: if any other part of the program uses the same string, the lock is shared because of interning
* a https://learn.microsoft.com/en-us/dotnet/visual-basic/language-reference/data-types/string-data-type[String] literal or instance: if any other part of the program uses the same string, the lock is shared because of interning
== How to fix it

Expand Down
4 changes: 2 additions & 2 deletions rules/S2551/why-dotnet.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,6 @@ A shared resource refers to a resource or data that can be accessed or modified

Shared resources should not be used for https://en.wikipedia.org/wiki/Lock_(computer_science)[locking] as it increases the chance of https://en.wikipedia.org/wiki/Deadlock[deadlocks]. Any other thread could acquire (or attempt to acquire) the same lock while doing some operation, without knowing that the resource is meant to be used for locking purposes.

One case of this is strings, which are https://en.wikipedia.org/wiki/Interning_(computer_science)[interned] by the runtime. This means that each string instance is immutable and stored, and then is reused everywhere it is referenced.
One example of this is a `String` https://en.wikipedia.org/wiki/Interning_(computer_science)[interned] by the runtime. This means that each `String` instance is immutable and stored, and then reused everywhere it is referenced.

Instead, a dedicated private `object` instance should be used for each shared resource. Making the lock-specific object `private` guarantees that the access to it is as minimal as possible, in order to avoid deadlocks or lock contention.
Instead, a dedicated private `object` instance should be used for each shared resource. Making the lock-specific object `private` guarantees that the access to it is as minimal as possible, in order to avoid deadlocks or lock contention.
2 changes: 1 addition & 1 deletion rules/S3923/description.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,4 @@ In the following code:

include::{example}[]

Either there is a copy-paste error that needs fixing or an unnecessary `switch` or `if` chain that needs removing.
Either there is a copy-paste error that needs fixing or an unnecessary `switch` or `if` chain that should be removed.

0 comments on commit a46b16a

Please sign in to comment.