In C#, it is good practice to add XML documentation to describe any exceptions that a method can throw. It is not difficult to add these for exceptions that you throw yourself. However, if I'm calling another method, and I've decided not to handle an exception thrown by this second method, there's no point in me re-writing existing documentation. I need to find the documentation for this second method and copy & paste it into the documentation for my method. Worse still are Framework methods, where I find myself copy & pasting little chunks of text from MSDN into my documentation.
Are there any tools that can automate this process? I'm thinking that there must be a plugin for VS that allows you to right-click a called method and select something like "Add Exception documentation to calling method documentation". Any suggestions would be helpful.
This sounds like a feature request for ghostdoc. It doesn't do this, but it does help with copying documentation when overriding a method or implementing an interface.
That being said, such a feature would have only limited usefulness because C# does not have checked exceptions like Java.
Related
I'm trying to make a custom FxCop rule that will test for calls to the indexer getter of Request.QueryString without a previous call (in the same method) to a certain validation method from our project's Utilities module.
The documentation I've found is not in-depth enough to get me where I need to go. Is there some doc that I'm missing? Or is it time for trial and error?
What I've seen:
http://www.binarycoder.net/fxcop/
http://blog.tatham.oddie.com.au/2010/01/06/custom-code-analysis-rules-in-vs2010-and-how-to-make-them-run-in-fxcop-and-vs2008-too/
http://blogs.msdn.com/b/codeanalysis/
http://msdn.microsoft.com/en-us/magazine/cc163930.aspx
As well as all SO posts tagged FxCop with the word custom.
Any ideas?
There is no official SDK for FxCop rules. The most complete single resource is http://www.binarycoder.net/fxcop/. Pretty much all the available resources are geared toward helping one get started with the "wrapper" mechanics of creating rules. None of them really cover the finicky details of how to create specific rule logic. For that sort of thing, your best bet is to grab a decompiler like Reflector so that you can see how the Microsoft-supplied rules are built. Another helpful technique is to run your embryonic rules under the debugger so that you can see the objects and properties that are available at runtime. If you get stuck with some particular part of a rule implementation, you can always ask about it either here or on the FxCop forum maintained by Microsoft.
Is there any way to know exact time complexity for .NET predefined methods. Like if I want to know the complexity for
String.Contains()
or
Hashtable.ContainsKey()
Does Microsoft share this information?
Yes, in MSDN :)
Hashtable.ContainsKey Method:
This method is an O(1) operation.
Enumerable.Contains Method (IEnumerable, TSource):
If the type of source implements
ICollection, the Contains method in
that implementation is invoked to
obtain the result. Otherwise, this
method determines whether source
contains the specified element.
Enumeration is terminated as soon as a
matching element is found.
So, for String it would be O(n).
A couple of posts have mentioned Reflector, which is a good tool but no longer free. A free tool that provides a similar service is ILSpy, worth a look if you don't want to buy reflector.
One possibility is using a tool like Reflector, and looking at the implementation of the methods yourself. You should then be able to determine the complexity for most methods (if they rely on many other methods, it might be cumbersome to trace your way through all the calls to do the calculation).
I do not think there is a page that explicitly lists the complexity for all methods.
You can find this out yourself very easily using Reflector and the Code Metrics addin.
Reflector is an obvious choice to find out the information you need as highlighted in other answers. However, this is no longer a free tool although not too expensive.
A free alternative is to look at the source code for the .NET framework libraries. Scott Guthrie has a post which provides some information and links to accessing and debugging the source code.
We have a Visual Studio 2010 solution that contains several C# projects in accordance with Jeffery Palermo's Onion Architecture pattern (http://jeffreypalermo.com/blog/the-onion-architecture-part-1/). We want to add the Visual Studio Intellisense Comments using the triple slashes, but we want to see if anyone knows of best practices on how far to take this. Do we start all the way down in the Model in the Core project, and work up through Infrastructure and into the DataAccess Services and Repositories, and into the User Interface? Or is it better to use these comments in a more limited fashion, and if so what are the important objects to apply the Intellisense Comments to?
Add them to any methods exposed in public APIs, that way you can give the caller all the information they need when working with a foreign interface. For example, which exceptions the method may throw and other remarks.
It's still beneficial to add these kinds of comments to private methods, I do it anyway to be consistent. It also helps if you plan on generating documentation from the comments.
While, technically, there is such a thing as too much documentation, 99.99999% of the time this exception doesn't apply.
Document everything as much as you can. Formal, informal, stream of thought..every scrap of comments will help some poor soul who inherits your code or has to interface with it.
(It's like the old rule "The error may be in the Compiler and not your code. Compilers have errors too. This is not one of those times.")
Do we start all the way down in the Model in the Core project, and work up through Infrastructure and into the DataAccess Services and Repositories, and into the User Interface? Yes
Or is it better to use these comments in a more limited fashion, and if so what are the important objects to apply the Intellisense Comments to? If you want to. Apply them to any function you write, and not what VS autogenerates
I've seen limited "intellisense" comments..but extensive in-code comments that follow. So long as the "content" is there, life will be good. I generally include a brief blurb about each function in the intellisense comments, but put the majority of "here's why i did this" in the function and dead-tree documents.
I agree with fletcher. Start with public facing classes and methods and then work your way down into private code. If you were starting from scratch I would highly recommend adding the XML comments to all code for your own convenience, but in this case starting with public methods and then updating other classes whenever you go in to update them is a good solution.
It occurs pretty often that I start debugging a class by logging every function call to console and looking for differences in the bugged cases.
Is there some attribute that I can apply to a class to enable such a tracing? It's pretty exhausting to have to enter these
Console.WriteLine("classname: methodname")
to every method and to remove them afterwards (removing can be done by conditional compilation, but it is not very nice to look at the code when you have all this redundance)
There was an add-on tool someone mentioned to me, using Attributes. Let's see if I can find it.
I think it was PostSharp:
Article
http://www.postsharp.org/
You can use PostSharp to intercept all method calls and print them even with all arguments and it does not require source code changes. This CodeProject article shows how to do logging with PostSharp.
Just to note, PostSharp is an aspect-oriented programming (AOP) framework and there are some more.
If log4net is as good as log4j, then you are all set
http://logging.apache.org/log4net//index.html
In the dim dark ages of software engineering, one often used a profiling tool to achieve that since profiling injected extra code at entry and exit of all functions, although I must say that this is a pretty dismal approach to debugging and when I used it, it was a desperation move not front line. Debugging by print statement is fairly slow and ineffective.
AOP is supported also by http://www.springframework.net/
Is there any way to find out what exceptions might be thrown by any method in .NET code? Ideally I want to see what might be thrown and choose which ones I want to handle. I guess I want the information you'd get from the throws clause in java.
The situation is I'm doing a linq query on an xml document from the network and want to know what could go wrong. I could open up the assembly in reflector and have a look but I thought there might be an easier way.
.NET does not have enforced ("checked") exceptions like java. The intellisense might show this information, if the developer has added a /// <exception.../> block - but ultimately more exceptions can happen than you expect (OutOfMemoryException, ThreadAbortException, TypeLoadException, etc can all happen fairly unpredictably).
In general, you should have an idea of what things are likely to go wrong, and which ones you can actually do something useful about. In most cases, the correct behaviour is to let the exception bubble up (just running any "finally" code to release resources).
Eric Lippert has a good blog on this subject here.
I think that Exception hunter can provide this information however it costs money...
After reading another article about this on StackOverflow, I built on top of that other answer to write a tool to do this, you can get the source code from GitHub here:
Exception Reflector
you can also read more here:
http://steves-rv-travels.com/archives/167
As long as you're using BCL classes, they are all completely documented and Intellisense therefore displays any exception a method can throw. Other than that (and reading the docs), there is no way, I think.