Adding Comments

Last but not least is the issue of producing readable code. One way to make your code more readable is to add comments. You probably noticed the comments throughout the code in the examples. Comments don't affect the processing of your code; they just make it more readable. C# has two types of comments: inline comments and block comments.

To add inline comments:

• At the end of a code line type two forward slashes (//) followed by the text for the comment ( Figure 2.87 ).

  Figure 2.87 Inline comments are handy for describing the purpose of fields, functions, and local variables . They are also often used above parts of the code to tell the reader what the code does.

   class Account {    int _Balance;  //keeps track of   //overall balance  int _LastDeposit;  //Amount of money   //last deposited  int AccountNum;  //Account number   //(unique identifier   //for account)  public int MakeDeposit(int Amount)    {      _Balance += Amount;      return _Balance;    } } 

To add block comments:

1. Type a forward slash followed by an asterisk (/*).

2. Type the comment text. It can be as short as a single character or as long as several paragraphs.

3. Type an asterisk followed by a backslash (*/) ( Figure 2.88 ).

   Figure 2.88 Block comments are normally used before a function or class to provide a history of changes made and more robust information about the portion of code.

    class Account {  /*   Function: MakeDeposit   Purpose : Increase or decrease   account's balance   Input   : int Amount - The amount to   deposit (can   be negative)   Output  : Total balance after   deposit.   */  public int MakeDeposit(int Amount)    {      _Balance += Amount;      return _Balance;    } } 

Tips

• You can insert block comments within a line of code ( Figure 2.89 ).

  Figure 2.89 Block comments are also useful for describing the purpose of parameters.

   class Account {    public int MakeDeposit    (int Amount  /*can be negative*/  ,    int Available  /*how much is   immediately available */  )    {      _Balance += Amount;      return _Balance;    } } 

• You can add inline comments to the end of every line even if the lines aren't complete program statements ( Figure 2.90 ).

  Figure 2.90 C# lets you break up statements into multiple lines. Each line can have an inline comment at the end of the line.

   class Account {    int _Balance;    public int MakeDeposit    (int Amount, int Available)    {      _Balance  //original balance  +=  //equals to original   //balance plus  (Amount  //amount deposited  -  //minus  Available);  //amount available  return _Balance;    } }