So I use XML Comments in my code to help explain Public Methods and Public Members, another developer has mentioned that not all of my methods have XML Comments. I use the rule, if public or protected, add XML comment, if private, don't.
Does this sound logical or is there some reason why you would XML Comment a private method?
There are no strong rules about comments, but I believe that it is good to comment public/internal/protected methods.
Sometimes I comment private methods when they are not very clear. Ideally code should be self-documented. For example if you have a method like
Item GetItemByTitle(string title)
then it is not required to write comments, because it's clear enough. But if a method could be unclear for other developers, please put your comments or rename/refactor the method event if it's private. Personally I prefer to read code, not comments :) If you have too many comments code becomes hard to read. My rule is to use comments only when it is required.
If on your project you have a convenience to document all methods including private methods, then follow this rule.
It makes sense to also comment private and protected members - possible reasons include:
another developer may need to use the code and a consistent commenting approach can prove helpful;
you may want to auto-generate a help/documentation file of the source code at some point; in this case, lack of Visual Studio XML comments can result in a lot of undocumented code.
I don't really see a good reason why you would limit XML comments to public members.
I subscribe to the guiding philosophy that a method should be simple enough that its signature describes exactly what it does. That being said, this is not always possible (especially when working with legacy code) so there are situations when a header comment is useful. Such as:
The methods use is not obvious (and cannot easily be refactored)
To generate api documentation
I don't think are really any hard and fast answers here, if it feels right to comment it then comment it
I always take it as a good practice to comment all my methods as equivalent to having to explain them to someone, as I would want to have them explained to me if I did not carry knowledge as to what is happening, and why.
We develop in a small team, and this really does help with team development. More so, I regularly use my OWN comments, to figure out what the heck my though process was 3 months ago when I look at a piece of code.
Absolutely worth it to spend some time in adding comments to the top of your methods / procedures that do some interesting stuff.
The question is a little unclear as to whether you are asking:
Should private code be commented in general? or
Assuming you do what to comment private code should you use XML or standard C# comments?
To comment or not
To answer the first question, needing to comment any code is a bit of a code smell. When you run into a situation that you run across code that is hard to read an needs explaining, your first attempt to solve that should be to change (usually by renaming things) so that the code is more readable. Using comments to explain an unclear method name should be a last resort.
There are some exceptions. Public methods of DLLs shared outside the solution should always be commented.
I recommend reading Robert C. (Uncle Bob) Martin's "Clean Code" book for more details on this.
XML or C# comments
In general, yes use XML comments for methods as opposed to C# comments. The XML comments show up in intellisense. Also, the XML comments are bound to the method and if you use refactoring tools to move methods the XML comments will be brought along with the method, whereas C# comments can easily be separated from the method.
One reason not to use XML comments is if you will be publicly distributing your DLL and the XML comment file. The XML file will contain comments for all your internal and private methods. So just make sure that you're OK with your customers potentially reading any of those comments on private methods.
Related
I recently found two posts in StackOverflow about adding comments in programming. Posts : 1,2
After going through these posts i was eager to know a thing a comments.i.e :
1.Do adding comments in programming utilize system resource while compiling the code ?
Yes they do, but you probably have to add a lot of them to notice any difference.
Handling white space and comments is part of the "lexing" (lexical analysis) phase of compilation, so yes, they do consume resources in the process. As a previous commenter has said, it's so computationally cheap that you'd have to insert a lot of comments and white space (and maybe compile on a really slow computer) before you'd notice.
You may be interested in this document: Notes on How Parsers and Compilers Work.
The first rule of programming: write code that other people can easily read and modify. To achieve this:
Write short, clear, code blocks that are easy to read and thus easy to determine the "what".
Write unit tests to both convey the "why" and to provide a safety net when maintaining the code.
Everything else, including how long the code takes to compile, should be moot. So the answer to your question is "it doesn't matter".
I wrote programs in procedural language (mostly VB6) since many years. Now I am learning C#. I read a couple of books and get things done but sometimes I ask myself: Should a method be in this class or in that class or somewhere else.
Here is an example: I write a console program which scans all files in a directory tree and will set NTFS security for all files according to some rules. For each “file type” (i.e. invoices, emails, Excel files) I have template files with the correct security settings.
My program does the following:
Read in the MyApp.exe.config where a log file should be written
Start the log file
Fill a list with details about the “file types” (currently hard coded)
Read in the MyApp.exe.config the locations and filenames of the template files from the above list
More steps
I have the classes Program with the Main method, FileWork which scans through the files, SecurityWork which sets NTFS security rights, and ApplConfig which reads and writes configuration information.
Now my question: Where should I put the method for my step 4 in above list? This concerns settings for the SecurityWork class which are read via the ApplConfig class. Should the method be in the SecurityWork class because it concerns the security settings, or should it be in the ApplConfig class because it reads information from the configuration file or should it be in the Program class? Technically all versions would work and I know how to write them.
I know there are OOP principles like Encapsulation and others involved. What I am looking for is not so much an answer to the above incomplete example but something like a set of questions I should ask myself to decide where methods which concern multiple classes should be.
Similar question were asked and answered before but most of the time I read answers like: you could do it like this or like that, it’s more or less up to you.
What do you suggest? Maybe a list with some questions, an article or a book?
To keep this question within the rules of Stackoverflow I am also happy to read an answer to the above example with an explanation of why it should be like this and not like that.
A short addition to this question: I think in many cases it is obvious in which class a method belongs. That is what I learned from books because they use often examples which are straight forward.
The “how do I do this?” happens only in some cases in which two or more classes are involved and the method could be in any of these classes and the program would work. The question is then: How would it work best? What is the best way to do this keeping future amendments in mind.
I appreciate already all the comments and answers up to now. Thanks.
Well, it's not really a question for stackoverflow, but I don't know where it would be better to ask it.
to your example the answer is to put the method for step 4 in the ApplConfig class, and have it send the values it's reading to the SecurityWork class.
Besides Encapsulation, there's this thing that's called the Single responsibility principle, that basically states that classes (and methods) should be responsible for one thing only.
Imagine a scenario where you want the location and file names to be stored in a database rather then in the app.config. By keeping the single responsibility principle all you have to change is one class and everything should work as it did before.
There are a lot of things to be said about the proper way to decide in which class a method belongs, but I think that this is probably one of the easiest to explain as well as understand, and it will give you the answer at least 80% of the time.
I would ask
Where will this have the lowest coupling to other objects?
Where can this go where it will have the fewest side effects (preferably no side effects)
Are there any useful patterns (see http://en.wikipedia.org/wiki/Software_design_pattern#Classification_and_list)
The customer has million lines of code (VB.Net and C#), and wants us to develop a tool to estimate the quality of the code.
What the information the customer wants to know include:
1）how many lines of comments in one code file
2) how many functions implemented in one class
3) whether all possible exception has been wrapped by a try/catch block
4) how many attributes attached to one function
5) ... (the customer said that the tool we provide should be configured and extensible so that they can implement more ideas later)
We plan to write a VS.Net add-on, which can parse the code of the opening project in time. seems the interesting thing in here is that we need to parsing the code of C# and VB.Net.
Please kindly provide some tips about how to start this interesting task.
Thanks in advanced!
You ask a very broad question, but you should begin by studying existing parser's APIs.
Once you do that you're golden.
For example look at this SO question which provides some parsers for C#. Of course you could write your own but I don't find any reason to since the task isn't very easy.
So you get your AST and once you do that you have all the information you want.
Keep in mind that if you reference a type that isn't in the file you must have to get it from another one, and it could also be a type from .NET. So there is definitely more work to be done.
To go through your list:
1）how many lines of comments in one code file: You could find it through your C# parser of choice. They recognize comment aswell
2) how many functions implemented in one class: Likewise, should be very easy
3) whether all possible exception has been wrapped by a try/catch block: Likewise, just find exception throws (the parser is likely to have a special type for language keywords, so looking for throw should be easy).
4) how many attributes attached to one function: and... Likewise
5) ... (the customer said that the tool we provide should be configured and extensible so that they can implement more ideas later): Shouldn't differ from any other project. Just make sure you're using good design principles, keeping everything abstract, using interfaces wisely, make your work in layers, etc. etc...
You can use Roslyn. For C# you can also use NRefactory.
Have a look at Stylecop, you may be able to add rules get the information you want?
http://stylecop.codeplex.com/
Lately I started using /// to comment my C# code rather than // or /* because it is just much simpler to use. Today I started wondering why there were different types and came across this SO question which states that /// comments are for generating the xml documentation.
I can't find any advice with regards to on type of comments vs another on Google and I take that to mean that it doesn't matter either way. I'm not getting any ill effects so far from using /// to comment, but I'd hate to get into a habit now just to unlearn it later. As far as I can tell, if there are no metatags in the comments it does not get recognised as being documentation (or am I completely wrong on that?)
Before I riddle my code with /// comments, is this type of commenting a big no-no? Could there be potential problems from commenting this way?
Could there be potential problems from commenting this way?
Yes. When you decide to generate your project documentation, then it will have all those commented lines as part of your XML documentation. When you compile the code using /Doc extension then it generates a document using your XML comments (///). If you have used that to comment out your code, then the document generate will consider the commented out code for your documentation.
Please see:
XML Documentation Comments (C# Programming Guide)
How to: Generate XML Documentation for a Project
There isn't any technical difference as far as code compilation goes. They're all ignored.
I believe the /// comment is more of a convention to signify that you are commenting a particular code block with XML Documentation Comments. IDEs like Visual Studio are geared to recognise the different comment type and will visually style accordingly.
Given that is general convention to use standard // or /* */ comments, there's also the potential to confuse (or, more likely, annoy) other developers who will read your code.
If you use delvelopment help tools like resharper for example mostly they offer you such a functionalities of commenting acode block either with // or with /* ... */, these commented code blocks can be toggeled using these tools, this wouldnt work for you once you have 3 slashes instead of 2.
The issue with the documentation symbols is another one, you will get comments generated in your documentation without having the control on what stayes a acomment in code and what gets into the documetnation since you have all over ///, but i guess this is an issue one can configure inthe documentation generation tool.
I find the xml doc comments for C# or VB.NET very hard to read. Is there a decent alternative (that still provides the benefits of documenting code for intellisense, doc generation, etc.)?
If readability is the problem you're trying to solve (i.e. reading XML is making your eyes wobble, which it does mine) you could add a stylesheet to the xml comments file. I started with the one referenced in this old post and modified from there. You'll have to add it back every time you build, but when you're documenting your changes for later reference (i.e. not using the docs a lot during active development) then it's not too bad.
I also use GhostDoc to make documentation a little less time-consuming.
Visual Studio's Intellisense only reads the XML documentation. Any other methods will end up generating it for you and will become out of date unless you're consistent in keeping things synchronized.
cr_documentor is another option. You use tha standard xml documentation (so intellisnese and other doc utilities stay happy). The human readable documentation is rendered in a window (docked or floating).
It may not be exactly what you want, but you might take a look at it.
Could try doxygen. Aside from having a refreshing name it has a lighter syntax. There are documentation generation tools and it claims to support C#.