Skip to content

Move all docs to the web site instead of the README. #199

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.

Sign up for GitHub

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

Merged
merged 2 commits into from
Nov 3, 2021
Merged

Move all docs to the web site instead of the README. #199

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fc885f4
Move all docs to the web site instead of the README.
Keboo Nov 3, 2021
15dc7a7
Moving action description back to README
Keboo Nov 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
162 changes: 1 addition & 161 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,164 +7,4 @@
[Coding Snippets Extension](https://marketplace.visualstudio.com/items?itemName=IntelliTect.intellitectsnippets)

# Coding Guidelines / Design Guidelines
A repository to contain IntelliTect's tools for coding conventions. [https://intellitect.github.io/CodingGuidelines/](https://intellitect.github.io/CodingGuidelines/)

## 00XX block - Naming
#### INTL0001 - Fields _PascalCase

Fields should be specified in _PascalCase. *Always* with a leading underscore, regardless
of visibility modifier.

**Allowed**
```c#
class SomeClass
{
public string _MyField;
}
```
**Disallowed**
```c#
class SomeClass
{
public string _myField;
public string myField;
}
```

#### INTL0002 - Properties PascalCase

Fields should be PascalCase

**Allowed**
```c#
class SomeClass
{
public string MyProperty { get; set; }
}
```

**Disallowed**
```c#
class SomeClass
{
public string myProperty { get; set; }
public string _MyProperty { get; set; }
}
```


#### INTL0003 - Methods PascalCase

Methods, including local functions, should be PascalCase

**Allowed**
```c#
class SomeClass
{
public string GetEmpty() {

var output = LocalFunction();

string LocalFunction() {
return string.Empty();
}

return output;
}
}
```

**Disallowed**
```c#
class SomeClass
{
public string getEmpty() {

var output = localFunction();

string localFunction() {
return string.Empty();
}

return output;
}
}
```



## 01XX block - Formatting
#### INTL0101 - Attributes on separate lines

All attributes should be on separate lines and be wrapped in their own braces.

**Allowed**
```c#
[FooClass]
[BarClass]
class SomeClass
{
[Foo]
[Bar]
public string MyProperty { get; set; }
}
```

**Disallowed**
```c#
[FooClass, BarClass]
class SomeClass
{
[Foo][Bar]
public string MyProperty { get; set; }
}
```


## 03XX block - Performance
#### INTL0301 - Favor using the method `EnumerateFiles` over the `GetFiles` method.

When using the `System.IO.Directory` class, it is suggested to use the `EnumerateFiles` static method
instead of the `GetFiles` method. In the remarks section of the [documentation](https://docs.microsoft.com/en-us/dotnet/api/system.io.directory.enumeratefiles), it is stated that using the `EnumerateFiles` method is more efficient because you can start enumerating the collection before all the results are returned:

> The EnumerateFiles and GetFiles methods differ as follows: When you use EnumerateFiles, you can start enumerating the
> collection of names before the whole collection is returned; when you use GetFiles, you must wait for the whole array of
> names to be returned before you can access the array. Therefore, when you are working with many files and directories,
> EnumerateFiles can be more efficient.
> The returned collection is not cached; each call to the GetEnumerator on the collection will start a new enumeration.

#### INTL0302 - Favor using the method `EnumerateDirectories` over the `GetDirectories` method.

When using the `System.IO.Directory` class, it is suggested to use the `EnumerateDirectories` static method
instead of the `GetDirectories` method. In the remarks section of the [documentation](https://docs.microsoft.com/en-us/dotnet/api/system.io.directory.enumeratedirectories), it is stated that using the `EnumerateDirectories ` method is more efficient because you can start enumerating the collection before all the results are returned:

> The EnumerateDirectories and GetDirectories methods differ as follows: When you use EnumerateDirectories, you can start
> enumerating the collection of names before the whole collection is returned; when you use GetDirectories, you must wait
> for the whole array of names to be returned before you can access the array. Therefore, when you are working with many
> files and directories, EnumerateDirectories can be more efficient.
> The returned collection is not cached; each call to the GetEnumerator on the collection will start a new enumeration.
>

#### INTL0303 - Unused local variable
TODO: Needs documentation

#### INTL0304 - Do not implicitly convert from `DateTime` to `DateTimeOffset`.

Implicit conversion of `DateTime` to `DateTimeOffset` determines timezone offset based on the `DateTime.Kind` value, and for
`DateTimeKind.Unspecified` it assumes `DateTimeKind.Local`, which may lead to differing behavior between running locally
and on a server. Code relying on certain behaviors may function correctly when run in tests locally because all code will
be running in the same timezone. This same code will fail or have different behavior when some of it is running in a hosted
environment like Azure where the time zone is often set to UTC.

See the feature proposal to remove this from the [dotnet corelib](https://github.com/dotnet/runtime/issues/32954).

> Misleading usecase is that TimeZoneInfo.ConvertTime has 2 overloads for DateTime and DateTimeOffset. When result of the
> first one is assigned to DateTimeOffset typed variable, DateTimeOffset record with local time zone offset is created.
> This is unclear for common code reader there's something unintended behaviour may take a place ((hey, I've supplied date,
> time and timezone to this function, and expect it to return date&time object for this timezone)), because types of either
> DateTime or DateTimeOffset that comes to ConvertTime argument may be masked by complex computational expression.


##### Guidelines Site Maintenance
There are two github actions that are used to update the CodingGuidelinesSite. One action ( *Update csharp Markdown* ) will run automatically when the XML file in the master branch is updated via a commit. The CodingGuidelines github page will then reflect the changes. After reviewing the "dev" site, there is another action ( *Update Docs Folder on CodingGuidelinesSite* ) that will move the new markdown file to production site [CodingGuidelinesSite]( https://intellitect.github.io/CodingGuidelinesSite/).
There is also another action to manually run a xml to md conversion on any branch.
A repository to contain IntelliTect's tools for coding conventions. [https://intellitect.github.io/CodingGuidelines/](https://intellitect.github.io/CodingGuidelines/)
27 changes: 26 additions & 1 deletion docs/analyzers/03XX.Performance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,4 +30,29 @@ instead of the `GetDirectories` method. In the remarks section of the [document

### When to suppress

Do not suppress a warning from this rule.
Do not suppress a warning from this rule.

#### INTL0303 - Local variable unused

All local variables should be accessed, or replaced with [discards](https://docs.microsoft.com/dotnet/csharp/fundamentals/functional/discards) (underscore character) to indicate they are unused.

#### INTL0304 - Do not implicitly convert from `DateTime` to `DateTimeOffset`.

Implicit conversion of `DateTime` to `DateTimeOffset` determines timezone offset based on the `DateTime.Kind` value, and for
`DateTimeKind.Unspecified` it assumes `DateTimeKind.Local`, which may lead to differing behavior between running locally
and on a server. Code relying on certain behaviors may function correctly when run in tests locally because all code will
be running in the same timezone. This same code will fail or have different behavior when some of it is running in a hosted
environment like Azure where the time zone is often set to UTC.

See the feature proposal to remove this from the [dotnet corelib](https://github.com/dotnet/runtime/issues/32954).

> Misleading usecase is that TimeZoneInfo.ConvertTime has 2 overloads for DateTime and DateTimeOffset. When result of the
> first one is assigned to DateTimeOffset typed variable, DateTimeOffset record with local time zone offset is created.
> This is unclear for common code reader there's something unintended behaviour may take a place ((hey, I've supplied date,
> time and timezone to this function, and expect it to return date&time object for this timezone)), because types of either
> DateTime or DateTimeOffset that comes to ConvertTime argument may be masked by complex computational expression.


##### Guidelines Site Maintenance
There are two github actions that are used to update the CodingGuidelinesSite. One action ( *Update csharp Markdown* ) will run automatically when the XML file in the master branch is updated via a commit. The CodingGuidelines github page will then reflect the changes. After reviewing the "dev" site, there is another action ( *Update Docs Folder on CodingGuidelinesSite* ) that will move the new markdown file to production site [CodingGuidelinesSite]( https://intellitect.github.io/CodingGuidelinesSite/).
There is also another action to manually run a xml to md conversion on any branch.