1. How to organize and document your classes
Based on Murach (ch. 16)

2. Objectives Applied Knowledge Add XML documentation to your classes.
Create and use a class library.
Knowledge
Describe two ways that you can code two or more classes in a single file.
Describe the benefits of creating and using a class library.
Describe the use of namespaces.
Describe the use of partial classes.

3. Classes and Files Normally each class is a separate file (.cs)
Closely related classes can be in the same file

4. Way 1. A file with two classes coded one after the other
public class Class1 {
// Body of Class1 }
public class Class2
// Body of Class2
Easy to create and manipulate
Not good for large classes
Good practice is one class from one file.
BUT if your application is quite small you can use several classes in one file.
(Ex.: Polymorphism – in the previous session)

5. Way 2. A file with nested classes
public class OuterClass {
InnerClass ic = new InnerClass();
// code that uses the inner class
// Body of OuterClass
public class InnerClass
// Body of InnerClass }
One class only make sense within context of the other
OuterClass.InnerClass ic = new OuterClass.InnerClass();

6. Bottom Line
When two classes are closely related, it sometimes makes sense to code them in the same file, especially if the classes are relatively small. That way, the project consists of fewer files.
In One way to code two classes in a single file is to code them one after the other
Another way to code two classes in a single file is to nest one class within the other.
This is useful when one Class is used only within the context of another class.
To refer to a nested class from another class, you must qualify it with the name of the class it’s nested within like this:
Outerclass.InnerClass

7. A Customer class that’s split into two files
If class is large (C# approach)
partial – means class may or may not be split across multiple source files.
Compiler combines all partial files in one.
All partial files must be in the same assembly
There are also partial methods
Cannot be public

8. Ex.: MSDN
public partial class Employee { public void DoWork() } public void GoToLunch()
The partial keyword indicates that other parts of the class, struct, or interface can be defined in the namespace. All the parts must use the partial keyword. All the parts must be available at compile time to form the final type. All the parts must have the same accessibility, such as public, private, and so on.
If any part is declared abstract, then the whole type is considered abstract. If any part is declared sealed, then the whole type is considered sealed. If any part declares a base type, then the whole type inherits that class.

9. Order of items in a class (good practice)
According to the StyleCop Rules Documentation the ordering is as follows.
Within a class, struct or interface: (SA1201 and SA1203)
Constant Fields
Fields
Constructors
Finalizers (Destructors)
Delegates
Events
Enums
Interfaces
Properties
Indexers
Methods
Structs
Classes

10. A Customer class that’s split into two files
partial – class may or may not be split across multiple source files.
The first file
public partial class Customer {
// Some members of the Customer class }
The second file
// The rest of the members of the Customer class

11. A Form class that’s split into two files
The Form1.cs file
public partial class Form1 : Form {
// The code for the Form1 class that's added
// by the programmer }
The Form1.designer.cs file (no need for public)
public partial class Form1
// The code for the Form1 class that's generated
// by Visual Studio

12. Namespaces Container of related classes
Every class belong to a namespace
Can nest namespaces
System.Collections is namespace Collections nested within System namespace
To use a class from another namespace – should include using

13. Code that declares a namespace
namespace ProductMaintenance {
public partial class Form1 : Form
// Body of Form1 class }  }
Good overview:

14. Code that declares nested namespaces (2 ways)
Way 1. to nest namespaces
namespace Murach {
namespace Validation
// Body of Validation namespace }
Way 2. to nest namespaces
namespace Murach.Validation
A using directive that specifies a namespace
using Murach.Validation;

15. Namespace Summary
A namespace is a container that can be used to group related classes.
In most cases, all of the classes that make up a C# project are part of the same namespace.
The namespace statement that appears near the beginning of a source file identifies the namespace that classes defined in that file belong to.
By default, when you add a class to a project, it’s added to a namespace with the same name as the project.
Namespaces can be nested. One way to nest namespaces is to include a namespace statement within the body of another namespace.
Another way is to code the fully-qualified name of the nested namespace in a namespace statement.
To use a class in a namespace other than the current namespace, you must either provide a using directive that names the other namespace, or you must qualify the class with the name of the namespace.

16. https://www.programiz.com/csharp- programming/namespaces
Reads
programming/namespaces
station.com/Tutorial/CSharp/Lesson06

17. Part of a Validator class with XML documentation
/// <summary> /// Provides static methods for validating data. /// </summary> public class Validator { public Validator() } /// The title that will appear in dialog boxes. public static string Title = "Entry Error";

18. Part of a Validator class with XML documentation cont.
/// <summary> /// Checks whether the user entered data into a text box. /// </summary> /// <param name="textBox">The text box control to be validated. /// </param> /// <returns>True if the user has entered data.</returns> public static bool IsPresent(TextBox textBox) { if (textBox.Text == "") MessageBox.Show(textBox.Tag + " is a required field.", Title); textBox.Focus(); return false; } return true;

19. XML elements for class documentation
Description
<summary>
Provides a general description of a class, property, method, or other element.
<value>
Describes the value of a property.
<returns>
Describes the return value of a method.
<param name="name">
Describes a parameter of a method.

20. A screen tip with documentation for a method
A screen tip with documentation for a parameter

21. Documentation XML
You can use special XML tags in C# source code to provide class documentation.
An XML documentation line begins with three slashes. Each documentation element begins with a start tag, such as <summary>, and ends with an and tag, such as </summary>. You code the description of the element between these tags.
If you type three slashes on the line immediately preceding a class or member declaration, Visual Studio automatically generates empty elements for you. Then,you just fill in the text that’s appropriate for each element.

22. Class Libraries: Two projects that use the Validator class

23. Two projects that access the Validator class via a class library
Can be re-used by different projects
One of the benefits of using class libraries is that the size of each project that uses them is reduced.
Projects reference class libraries
Change only in one place (!) – effective immediately in both projects

24. Class Libraries
Class libraries provide a central location for storing classes that are used by two or more applications. When you store a class in a Class library, you don’t have to include the class in each application that uses it. Instead, you include a reference to the class library in those applications.
When you modify a class in a class library, the changes are immediately available to all applications that use the library.
To create a class library, you develop a class library project. Then, when you build the project, Visual Studio creates a DLL file for the class library. It’s this DLL that you refer to from any application that needs to use the class library.

25. Creating Class Library Project
New->Project->Class Library
or/and
Class1.cs Add Existing Item to add classes
References include other libraries
Assembly is dll
Use Release ->bin\Release
See

26. A class library project Murach.Validation

27. A project with a reference to a class library
Add Reference -> Browse

28. A using directive for the validation class library
using Murach.Validation;

29. Summary: create a class library project
To create a class library project, display the New Project dialog box. Then, select the Class Library template and enter a name and location for the project.
By default, a class library project includes a single class named Class1. You can modify this class any way you want or delete it from the project. You can also add new classes using the Project- >Add Class command, and you can add classes from another project using the Project->Add Existing Item command.
You should create a namespace for your class library that indicates the purpose of the classes contained in the library.
In the previous example, the namespace is Murach.Validation.To compile a class library project, select the Release option from the Solution Configurations combo box in the Standard toolbar. Then, select the Build->BuildSolution command. The class library is compiled into a DLL file that’s stored in the bin\Release folder for the project.

30. Summary: add/use a class library project
Add a reference to the class library to your project by right-clicking the References folder in the Solution Explorer and selecting the Add Reference command. In the Reference Manager dialog box, display the Browse page, click the Browse button, locate the DLL for the class library, select it, and click the OK button.
If the class library project is included in the same solution as the client project, that project will appear in the list on the Projects page. Then, you can add a reference for the class library by double- clicking the project name.
Once you have added a reference to the class library, you can include a using directive for the class library’s namespace in any class that uses it.
You can then use the classes in the class library without qualification. Alternatively, you can qualify the class names with the namespace name you assigned to the library.