Skip to content
This repository was archived by the owner on Aug 18, 2021. It is now read-only.

Commit f732504

Browse files
authored
docs: improved CONTRIBUTING
Added a few clarifications.
1 parent ac834f4 commit f732504

File tree

1 file changed

+12
-9
lines changed

1 file changed

+12
-9
lines changed

CONTRIBUTING.md

+12-9
Original file line numberDiff line numberDiff line change
@@ -65,13 +65,13 @@ TODO
6565
The general naming pattern is `Liquid.<area>.<subarea>`.
6666

6767
## Unit tests
68-
We use xUnit.net for all unit testing.
68+
We use xUnit.net for all unit testing. Additionally, you can use nSubstitute for mocks and such, and leverage AutoFixture for anonymous instances.
6969

7070
## Code Style
7171

7272
### General
7373

74-
The most general guideline is that we use all the VS default settings in terms of code formatting, except that we put System namespaces before other namespaces (this used to be the default in VS, but it changed in a more recent version of VS).
74+
The most general guideline is that we use all the VS default settings in terms of code formatting, except that we put System namespaces before other namespaces (this used to be the default in VS, but it changed in a more recent version of VS). Also, we are leveraging StyleCop to add to code standardization.
7575

7676
1. Use four spaces of indentation (no tabs)
7777
1. Use `_camelCase` for private fields
@@ -161,7 +161,7 @@ As a modern set of frameworks, usage of internal types and members is allowed, b
161161

162162
`InternalsVisibleTo` is used only to allow a unit test to test internal types and members of its runtime assembly. We do not use `InternalsVisibleTo` between two runtime assemblies.
163163

164-
If two runtime assemblies need to share common helpers then we will use a "shared source" solution with build-time only packages. Check out the some of the projects in https://github.com/aspnet/Common/ and how they are referenced from other solutions.
164+
If two runtime assemblies need to share common helpers then we will use a "shared source" solution with build-time only packages.
165165

166166
If two runtime assemblies need to call each other's APIs, the APIs must be public. If we need it, it is likely that our customers need it.
167167

@@ -219,11 +219,11 @@ Code style is usually enforced by Analyzers; any change to those rules must be d
219219

220220
The items below point out the good practices that all code should follow.
221221

222-
### Zero warnings
222+
#### Zero warnings
223223

224224
Compiler warnings should usually be dealt with by correcting the code. Only discussed warnings may be allowed to be marked as exceptions.
225225

226-
### Inner documentation
226+
#### Inner documentation
227227

228228
All public members must be documented. Documentation should clarify the purpose and usage of code elements, so comments such as FooManager: "manages foo" will be rejected. Classes that implement interface may use comment inheritance `/// <inheritdoc/>`, but use it sparingly.
229229

@@ -251,7 +251,7 @@ All comments should be read-proof.
251251

252252
The unit tests for the `Liquid.Fruit` assembly live in the `Liquid.Fruit.Tests` assembly.
253253

254-
The functional tests for the `Microsoft.Fruit` assembly live in the `Microsoft.Fruit.AcceptanceTests` assembly.
254+
The functional tests for the `Liquid.Fruit` assembly live in the `Microsoft.Fruit.AcceptanceTests` assembly.
255255

256256
In general there should be exactly one unit test assembly for each product runtime assembly. In general there should be one functional test assembly per repo. Exceptions can be made for both.
257257

@@ -261,10 +261,13 @@ Test class names end with Test and live in the same namespace as the class being
261261

262262
#### Unit test method naming
263263

264-
Unit test method names must be descriptive about what is being tested, under what conditions, and what the expectations are. Pascal casing and underscores can be used to improve readability. The following test names are correct:
264+
Unit test method names must be descriptive about what is being tested, under what conditions, and what the expectations are. Pascal casing and underscores can be used to improve readability. We will try to follow [Roy Osherove's guidelines](https://osherove.com/blog/2005/4/3/naming-standards-for-unit-tests.html), therefore, the following test names are correct:
265+
266+
`GetAttachmentWhenItWasInsertedReturnsInsertedData`
267+
`GetWhenAttachmentDoesntExistsThrows`
268+
269+
> Notice how we use When and Returns / Throws to split the name into recognizable parts.
265270
266-
`PublicApiArgumentsShouldHaveNotNullAnnotation`
267-
`Public_api_arguments_should_have_not_null_annotation`
268271
The following test names are incorrect:
269272

270273
```

0 commit comments

Comments
 (0)