Commenting Exceptions

  • Thread starter Thread starter C# Learner
  • Start date Start date
C

C# Learner

Consider:

public void PublicMethod() {
DoSomething();
DoSomethingElse();
}

void DoSomething() {
if (!TryParse(data)) {
throw new FooException();
}
}

void DoSomethingElse() {
if (!TryProcess(something)) {
throw new BarException();
}
}

How should one comment these exceptions? Should one simply comment that
PublicMethod can throw FooExceptions and BarExceptions? Should one comment
that the private methods can throw exceptions too?
 
If we are talking standard (non-XML comments) then its a good idea to
document all methods as these are used by teh maintainers of the code.
Click to expand...

Consider:

/// <exception cref="AE">Blah.</exception>
/// <exception cref="BE">Blah.</exception>
/// <exception cref="CE">Blah.</exception>
/// <exception cref="DE">Blah.</exception>
public void Foo() {
A();
B();
C();
D();
}

/// <exception cref="AE">Blah.</exception>
void A() {
throw new AE();
}

/// <exception cref="BE">Blah.</exception>
void B() {
throw new BE();
}

/// <exception cref="CE">Blah.</exception>
void C() {
throw new CE();
}

/// <exception cref="DE">Blah.</exception>
void D() {
throw new DE();
}

The problem here is that there are a whole load of comments to maintain,
and many are duplicates too.

For a less trivial example, it seems like too much overhead, so I'm
wondering if there's a decent compromise here...
 
[...] I don't think Foo should document that at all
since it is very brittle and error prone. Instead, I document whether or not
any exceptions are allowed to escape Foo in a Remaks section, and only
document the methods that actually throw an exception, as you have done for
methods A, B, C, and D. [...]
Click to expand...

I like this idea. I'll use this and see how it goes.

Thanks.
 
If we are talking standard (non-XML comments) then its a good idea to document all methods as these are used by teh maintainers of the code.

If we are talking XML comments then it depends on who you are deigning the comments for. If for consumers of your component then only document the public/protected members, if for the maintainers of the code then document all.

Regards

Richard Blewett - DevelopMentor
http://staff.develop.com/richardb/weblog

nntp://news.microsoft.com/microsoft.public.dotnet.languages.csharp/<[email protected]>

Consider:

public void PublicMethod() {
DoSomething();
DoSomethingElse();
}

void DoSomething() {
if (!TryParse(data)) {
throw new FooException();
}
}

void DoSomethingElse() {
if (!TryProcess(something)) {
throw new BarException();
}
}

How should one comment these exceptions? Should one simply comment that
PublicMethod can throw FooExceptions and BarExceptions? Should one comment
that the private methods can throw exceptions too?

---
Incoming mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.771 / Virus Database: 518 - Release Date: 28/09/2004



[microsoft.public.dotnet.languages.csharp]
 
C# Learner said:
Consider:

/// <exception cref="AE">Blah.</exception>
/// <exception cref="BE">Blah.</exception>
/// <exception cref="CE">Blah.</exception>
/// <exception cref="DE">Blah.</exception>
public void Foo() {
A();
B();
C();
D();
}

/// <exception cref="AE">Blah.</exception>
void A() {
throw new AE();
}

/// <exception cref="BE">Blah.</exception>
void B() {
throw new BE();
}

/// <exception cref="CE">Blah.</exception>
void C() {
throw new CE();
}

/// <exception cref="DE">Blah.</exception>
void D() {
throw new DE();
}

The problem here is that there are a whole load of comments to maintain,
and many are duplicates too.

For a less trivial example, it seems like too much overhead, so I'm
wondering if there's a decent compromise here...
Click to expand...

I use a different strategy. The problem I have with commenting Foo() is that
Foo itself does not throw those exceptions, the methods it calls are the
ones that actually throw it. I don't think Foo should document that at all
since it is very brittle and error prone. Instead, I document whether or not
any exceptions are allowed to escape Foo in a Remaks section, and only
document the methods that actually throw an exception, as you have done for
methods A, B, C, and D.

What is really needed is a tool that can evaluate the methods for the
exceptions they can throw so the entire process is automated and correct.
 
Back
Top