How to organize and document your classes

1. How to organizeand documentyour classes Based on Murach (ch.16)

2. Objectives • Applied • 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 • 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) publicclass Class1 { // Body of Class1 } publicclass Class2 { // Body of Class2 }

5. Way 2. A file with nested classes • One class only make sense within context of the other • OuterClass.InnerClassic = new OuterClass.InnerClass(); publicclassOuterClass { InnerClassic = new InnerClass(); // code that uses the inner class // Body of OuterClass publicclassInnerClass { // Body of 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 The partialkeyword 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. public partial class Employee { public void DoWork() { } } public partial class Employee { public void GoToLunch() { } }

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 publicpartial class Customer { // Some members of the Customer class } The second file publicpartial class Customer { // The rest of the members of the Customer class }

11. A Form class that’s split into two files The Form1.cs file publicpartial class Form1 : Form { // The code for the Form1 class that's added // by the programmer } The Form1.designer.csfile(no need for public) publicpartial 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 namespaceProductMaintenance { publicpartialclass Form1 : Form { // Body of Form1 class } } Good overview: http://csharp-station.com/Tutorial/CSharp/Lesson06

14. Code that declares nested namespaces (2 ways) Way 1. to nest namespaces namespaceMurach { namespace Validation { // Body of Validation namespace } } Way 2. to nest namespaces namespace Murach.Validation { // Body of Validation namespace } A using directive that specifies a namespace usingMurach.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. Reads https://www.programiz.com/csharp-programming/namespaces https://csharp-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() { } /// <summary> /// The title that will appear in dialog boxes. /// </summary> 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(TextBoxtextBox) { if (textBox.Text == "") { MessageBox.Show(textBox.Tag + " is a required field.", Title); textBox.Focus(); return false; } return true; }

19. XML elements for class documentation

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,youjust 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 https://www.youtube.com/watch?v=WUWp9E66y_A https://www.youtube.com/watch?v=x-KK7bmo1AM

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 usingMurach.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.Tocompile a class library project, select the Release option from the Solution Configurations combo box in the Standard toolbar. Then, select the Build->BuildSolutioncommand. The class library is compiled into a DLL file that’s stored in the bin\Releasefolder 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 Browsebutton, locate the DLL for the class library, select it, and click the OKbutton. 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.