We need something to explain the mystery and thats

Info icon This preview shows pages 49–51. Sign up to view the full content.

View Full Document Right Arrow Icon
these characteristics are rarely desirable in code. We need something to explain the mystery, and that’s the purpose of a comment. So you might write this: // Frobnicator v2.41 has a bug where it crashes occasionally if // we try to set the target to "Norfolk". Setting it to an empty // string first seems to work around the problem. Frobnicator.SetTarget(""); Frobnicator.SetTarget("Norfolk"); This is now less mysterious. Someone coming across this code knows why the appa- rently redundant line was added. It’s clear what problem it solves and the conditions under which that problem occurs, which makes it possible to find out whether the problem has been fixed in the most recent version of the offending component, making it possible to remove the fix. This makes it much easier to maintain code in the long run. As far as C# is concerned, this example is identical to the one without comments. The // character sequence tells it to ignore any further text up to the end of the line. So you can either put comments on their own line as shown earlier, or tack them onto the end of an existing line: Frobnicator.SetTarget(""); // Workaround for bug in v2.41 Like most of the C-family languages, C# supports two forms of comment syntax. As well as the single-line // form, you can write a comment that spans multiple lines, denoting the start with /* and the end with */ , for example: /* This is part of a comment. This continues to be part of the same comment. Here endeth the comment. */ Comments, Regions, and Readability | 25
Image of page 49

Info iconThis preview has intentionally blurred sections. Sign up to view the full version.

View Full Document Right Arrow Icon
Bad Comments While comments can be very useful, many, sadly, are not. There are a couple of particularly common mistakes people make when writing comments, and it’s worth drawing attention to them so that you know what to avoid. Here’s the most common example: // Setting target to empty string Frobnicator.SetTarget(""); // Setting target to Norfolk Frobnicator.SetTarget("Norfolk"); These comments just repeat what the code already said. This is clearly a waste of space, but it’s surprisingly common, particularly from inexperienced developers. This may be because they’ve been told that comments are good, but they have no idea what makes a good comment. A comment should say something that’s not obvious from the code and which is likely to be useful to anyone trying to understand the code. The other common form of bad comment looks like this: // Setting target to Norfolk Frobnicator.SetTarget("Wiltshire"); Here, the comment contradicts the code. It seems like it shouldn’t be necessary to say that you shouldn’t do that, but it’s surprising how often you see this sort of thing in real code. It usually happens because someone modified the code without bothering to update the comment. A quick review of the comments after a code change is always worth doing. (Not least because if you’ve not paid enough attention to detail to notice that the comments are no longer accurate, chances are there are other problems you’ve not noticed.) XML Documentation Comments If you structure your comments in a certain way, Visual Studio is able to present the information in those comments in tool tips whenever developers use your code. As
Image of page 50
Image of page 51
This is the end of the preview. Sign up to access the rest of the document.

{[ snackBarMessage ]}

What students are saying

  • Left Quote Icon

    As a current student on this bumpy collegiate pathway, I stumbled upon Course Hero, where I can find study resources for nearly all my courses, get online help from tutors 24/7, and even share my old projects, papers, and lecture notes with other students.

    Student Picture

    Kiran Temple University Fox School of Business ‘17, Course Hero Intern

  • Left Quote Icon

    I cannot even describe how much Course Hero helped me this summer. It’s truly become something I can always rely on and help me. In the end, I was not only able to survive summer classes, but I was able to thrive thanks to Course Hero.

    Student Picture

    Dana University of Pennsylvania ‘17, Course Hero Intern

  • Left Quote Icon

    The ability to access any university’s resources through Course Hero proved invaluable in my case. I was behind on Tulane coursework and actually used UCLA’s materials to help me move forward and get everything together on time.

    Student Picture

    Jill Tulane University ‘16, Course Hero Intern