Multi-module Assemblies

Problem
You have more than one module and are considering merging it as one assembly. Should you do it?

Solution
Avoid multi-module assemblies. In most cases, you can deploy an application as one main EXE plus zero or more DLLs without creating multi-module assemblies.

Comments
Compiling multi-module assemblies requires using the Al.exe command-line tool, and this slows down the build process. The main advantage of having a single assembly composed of multiple modules rather than multiple distinct assemblies is that types marked as internal are visible to types in other modules. If you have distinct assemblies, you must mark these types public to make them callable by another assembly. However, in this scenario, you can’t easily prevent other assemblies from using your types. Multi-module assemblies are required when you have to merge modules written in different languages into one assembly. But, in such cases, you should consider splitting the application into distinct assemblies (one per language).

Size of Assemblies

Problem
You want to know how large your assemblies should be.

Solution
In general, prefer few large assemblies to many smaller ones. If you have a group of types that are always loaded and used together, place them in the same assembly. If you have two or more assemblies that are always loaded and used together, merge them into a single assembly.

Comments
The .NET runtime loads a large assembly faster than several smaller ones. A single, larger assembly creates a smaller working set of the application, and Ngen.exe can optimize it more effectively. On the other hand, you may need to split a larger assembly into several smaller ones if the types in it need to be assigned different identities or trust levels.

Strong Names for Assemblies

Problem
You want to know the benefits of strong-named assemblies.

Solution
Strong-naming creates a unique identity for an assembly and can prevent assembly conflicts. Always sign DLL and EXE assemblies with a strong name.

Comments
Specify the path of your company’s .snk file in the AssemblyKeyFile attribute in AssemblyInfo.cs. You can generate the .snk file holding private and public keys of your company by running the Sn.exe command-line tool.

TODO and HACK Comment Tokens

Problem
You want to know how to use special comment tokens TODO and HACK.

Solution
Use TODO to mark unfinished portions of your code and HACK to tag portions of code that use hard-to-understand techniques.

Comments
You can display TODOs in Rider by opening the TODO window from the View | Tool Windows menu.

Example

// TODO: Add code to wait for app here.
...

// HACK: Use of undocumented third-party API here.
...

Commenting out Code in C#

Problem
You want to know the best way to comment out blocks of code.

Solution
Use single-line comments instead of block comments to comment out blocks of code. Be sure to place the // symbol in the first column. This helps make it clear that it isn’t a standard comment.

Comments
Avoid commenting out executable lines of code; especially, before checking it in. Lines of code that are commented out and ignored tend to become dead code.

Comments for Auto-generated Code

Problem
You’d like to know how to document code that’s been generated by a tool.

Solution
Include a comment at the top of the source file that explains how the code was generated and that it shouldn’t be manually edited.

Example

//--------------------------------------------------------
// <autogenerated>
//    This code was generated by ReSharper.
//    Version: 1.1.0
//
//    Changes to this file may cause unstable behavior
//    and will be lost if the code is regenerated.
// </autogenerated>
//--------------------------------------------------------

Comments for Overloaded Methods

Problem
You want to know how to document overloaded methods.

Solution
Don’t repeat the same comment for all versions of an overloaded method. Instead, use a thorough description for the version with more arguments and include a short comment for simpler ones.

Comments
This technique cannot be adopted if you’re using XML comments, because the compiler will create documentation for just one of the methods in the group.

Statement-Level Comments in C#

Problem
What about statement-level comments? How should you handle those?

Solution
In general, avoid statement-level comments. One exception may be when you need to explain what a variable or argument does.

Comments
Statement-level comments are those that are on the same line and to the right of code.

Examples

// Incorrect.
while ( doc.Read() )     // Read all records.
{
    ...
}

// Correct.
// Read all records.
while ( doc.Read() )
{
    ...
}

// Correct.
string inputFile;       // Input file.
string outputFile;      // Output file.

// Correct.
void LoginWith(var userName,    // User's username.
    var password                // User's password.
    );