Questions about Coding Practices

[wangdaixing]

I am reading "Programming .NET Components" 2nd Edition by Juval Lowy,
O'Reilly. In Appendix E, there is a chapter "Coding Practices" which I
agree and practice mostly. However, there are a few items I don't
quite understand why as listed below, my questions are marked Q:

10. Avoid method-level document.
a. Use extensive external documentation for API documentation.
b. Use method level comments only as tool tips for other developers.

Q: Visual Studio and SandCastle have provided comprehensive support
for in-source document, so I would thin that method-level
documentation is encouraged. For example, in IDE, after you add /// on
the top of a method, framework of in-source document for the method is
created.

29. Avoid using the trinary conditional operator.

Q: Is it really hard to read?

35. Always mark public and protected methods as virtual in a non-
sealed class.

Q: what is the incentive to mark all as virtual?

58. Do not use late-binding invocation when early binding is possible.

Q: Microsoft Application Blocks seem to encourage the uses of late-
binding invocation. Personally I like early binding as the compiler
may check errors for me.



Can you answer or make a comment?

Cheers

Daixing

 

[Chakravarthy]

the trinary conditional operator compiles the entire statement before it
actually execute them. if there is any error in any of the statements it
will not execute the whole statement.

For example..

string strX = (y < 0) ? (x>0) ? "Positive Number" :
"Non Positive Number" : (z>10)? "Greater than Ten Value" : "Less than Ten
Value";

In this above code, if there is any error in any statement, the entire line
will not execute.

That's the reason, it is not recommended to use Trinary. At the same time,
if you are very sure that there will not be any issues with the values for
the variables that are used with in the conditions, it is highly
recommended.

HTH

 

[Peter Morris]

10. Avoid method-level document.

a. Use extensive external documentation for API documentation.
b. Use method level comments only as tool tips for other developers.

Does he say why? Why would you not document a method in code? If your
documentation is separate it is more likely to be out of sync with the
method. I would document in the source *or* use a tool like doc-o-matic
which at least reads the source (I would prefer this, it keeps your source
smaller).

29. Avoid using the trinary conditional operator.

Q: Is it really hard to read?

For very long lines it can be hard to read, for short stuff it isn't. I use
if/else for long lines and trinary where it is short enough.

35. Always mark public and protected methods as virtual in a non-
sealed class.

At this point I would have stopped reading the book.

58. Do not use late-binding invocation when early binding is possible.

Q: Microsoft Application Blocks seem to encourage the uses of late-
binding invocation. Personally I like early binding as the compiler
may check errors for me.

It says "when early binding is possible". Compile time checks are better
than runtime ones, but if early binding isn't possible then you can't use
it. This one makes sense, what is your objection?



Pete

 

[Jon Skeet [C# MVP]]

the trinary conditional operator compiles the entire statement before it
actually execute them. if there is any error in any of the statements it
will not execute the whole statement.

That's true of *all* C# code. The whole C# file is compiled before any
of it is executed.

It sounds like you're thinking of something like JavaScript.

Jon

 

[Pavel Minaev]

10. Avoid method-level document.
a. Use extensive external documentation for API documentation.
b. Use method level comments only as tool tips for other developers.

Q: Visual Studio and SandCastle have provided comprehensive support
for in-source document, so I would thin that method-level
documentation is encouraged. For example, in IDE, after you add /// on
the top of a method, framework of in-source document for the method is
created.

When you are really trying to match the detail level of MSDN, using
documentation comments inside the source file quickly becomes unwieldy
- simply because you'll have a screenful of comments before each and
every method. If you really do need that level of detail, you might
want to consider including the bulk of documentation from an external
XML file - that's the way Microsoft does it, if you look at .NET
framework source code. You can use the <include> element for that.
Such XML files are typically more convenient to edit, too, especially
if you use a dedicated visual XML authoring tool.

29. Avoid using the trinary conditional operator.

Q: Is it really hard to read?

It is, if it is nested, or if its operands are long expressions
(though in the latter case, splitting it into three lines helps). But
for simple expressions, it is usually easier that a corresponding if-
else, especially if you also have a policy of always putting braces.

35. Always mark public and protected methods as virtual in a non-
sealed class.

Q: what is the incentive to mark all as virtual?

None whatsoever. "virtual" is not the default in C# for a reason, and
it was a conscious language design decision. Read this for an
explanation:

http://www.artima.com/intv/nonvirtual.html

 

[J.B. Moreno]

That's true of *all* C# code. The whole C# file is compiled before any
of it is executed.

It sounds like you're thinking of something like JavaScript.

He's probably thinking of VB's IIF where something like

IIF (ISNULL(myVar), false.tostring(), myvar.tostring())

will cause an exception if myvar is null.

 

[wangdaixing]

[...]

Q: what is the incentive to mark all as virtual?

None whatsoever. "virtual" is not the default in C# for a reason, and
it was a conscious language design decision. Read this for an
explanation:

http://www.artima.com/intv/nonvirtual.html

For what it's worth, I had not seen this article before.  You can startat  
the beginning here:http://www.artima.com/intv/anders.html

I _highly_ recommend the interview to anyone with any interest in C# at  
all.  It's very informative, and just plain interesting.  (I also learned  
that one of the C# 2.0 designers is a guy I worked with a decade or so  
ago...that was pretty neat to find out too ).

I haven't had a chance to check out the rest of the web site, but if the  
interview is any indication, it looks like it's a pretty good resource for  programmingtopics generally.  Thanks for the link Pavel!

Pete

Thanks all who reply, I got really good corrections and inspiration.
In particular, Artima.com about Anders is excellent. I myself started
commercial programming with Turbo Pascal, then Delphi. I am glad
Anders found a good environment of working in "evil" Microsoft and
gave us C#.