Questions about Coding Practices

[wangdaixing@gmail.com]

I am reading "Programmin g .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

[Peter Duniho]

Re: Questions about Coding Practices

On Sun, 13 Jul 2008 22:11:48 -0700, <wangdaixing@gm ail.comwrote:

I am reading "Programmin g .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.

I'm not entirely clear on what the book is proposing. That is, what it
considers "method-level". However, I wonder if the "top of the method"
documentation you're describing is more like the "external documentation"
the book mentions. That is, I know it's not technically external, but it
winds up being that to some extent.

What I _would_ recommend eschewing, and perhaps this is what the book
means also, are comments _within_ the method body. Not that they should
be avoided entirely, but that they should be reserved for things that
aren't self-explanatory in the code. And of course, the code should be
written in a way that makes it as self-explanatory as possible, minimizing
the need for any comments in the method body itself.

Redundant comments just waste people's time, and _all_ comments have the
risk of becoming out-of-sync with the code. The code is always an
accurate description of the code, but a comment may not be. :)

29. Avoid using the trinary conditional operator.
>
Q: Is it really hard to read?

I don't know why the book is recommending against it specifically, but
sure...it can certainly obfuscate patterns in the code. On the other
hand, when used judiciously, it can help readability. The key is to know
when to use it.

35. Always mark public and protected methods as virtual in a non-
sealed class.
>
Q: what is the incentive to mark all as virtual?

I personally disagree with the book's advice here. Perhaps the author is
used to Java where virtual is the default for everything? In any case,
it's really a matter of philosophy and I doubt there'd be much consensus
on that particular question. But it's my feeling that it's generally
better not to make things virtual unless you are specifically intending
and expecting that they would be overridden in sub-classes.

I can see the point of view of the book, to some extent. After all, if
you intend for a class to be sub-classed (i.e. it's not sealed), why not
give inheritors the maximum amout of flexibility? But IMHO the problem
with that point of view is that one can more easily ensure the code is
robust if you can make some assumptions about what parts of the
implementation may or may not change. Making everything virtual opens the
possibility that the entire implementation might change.

Even a single virtual member opens the door to a certain class of bugs in
that respect, but the more virtual members you have, the more
opportunities for such bugs exist, and those opportunities increase in an
exponential way due to the increasing degree of potentially incorrect
interactions between various virtual members.

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.

I don't know anything about "Microsoft Application Blocks" and can't
evaluate your statement that they "encourage the uses of late-binding
invocation". But I tend to agree with the view proposed by the book and
you. IMHO, late-binding is for situations where early-binding is
impossible, or where you have a desire for a more flexible API that
late-binding would provide.

Pete

[Chakravarthy]

Re: Questions about Coding Practices

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 Duniho" <NpOeStPeAdM@nn owslpianmk.comw rote in message
news:op.ud9oagy w8jd0ej@petes-computer.local. ..

On Sun, 13 Jul 2008 22:11:48 -0700, <wangdaixing@gm ail.comwrote:
>

>I am reading "Programmin g .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
>documentatio n 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.

>
I'm not entirely clear on what the book is proposing. That is, what it
considers "method-level". However, I wonder if the "top of the method"
documentation you're describing is more like the "external documentation"
the book mentions. That is, I know it's not technically external, but it
winds up being that to some extent.
>
What I _would_ recommend eschewing, and perhaps this is what the book
means also, are comments _within_ the method body. Not that they should
be avoided entirely, but that they should be reserved for things that
aren't self-explanatory in the code. And of course, the code should be
written in a way that makes it as self-explanatory as possible, minimizing
the need for any comments in the method body itself.
>
Redundant comments just waste people's time, and _all_ comments have the
risk of becoming out-of-sync with the code. The code is always an
accurate description of the code, but a comment may not be. :)
>

>29. Avoid using the trinary conditional operator.
>>
>Q: Is it really hard to read?

>
I don't know why the book is recommending against it specifically, but
sure...it can certainly obfuscate patterns in the code. On the other
hand, when used judiciously, it can help readability. The key is to know
when to use it.
>

>35. Always mark public and protected methods as virtual in a non-
>sealed class.
>>
>Q: what is the incentive to mark all as virtual?

>
I personally disagree with the book's advice here. Perhaps the author is
used to Java where virtual is the default for everything? In any case,
it's really a matter of philosophy and I doubt there'd be much consensus
on that particular question. But it's my feeling that it's generally
better not to make things virtual unless you are specifically intending
and expecting that they would be overridden in sub-classes.
>
I can see the point of view of the book, to some extent. After all, if
you intend for a class to be sub-classed (i.e. it's not sealed), why not
give inheritors the maximum amout of flexibility? But IMHO the problem
with that point of view is that one can more easily ensure the code is
robust if you can make some assumptions about what parts of the
implementation may or may not change. Making everything virtual opens the
possibility that the entire implementation might change.
>
Even a single virtual member opens the door to a certain class of bugs in
that respect, but the more virtual members you have, the more
opportunities for such bugs exist, and those opportunities increase in an
exponential way due to the increasing degree of potentially incorrect
interactions between various virtual members.
>

>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.

>
I don't know anything about "Microsoft Application Blocks" and can't
evaluate your statement that they "encourage the uses of late-binding
invocation". But I tend to agree with the view proposed by the book and
you. IMHO, late-binding is for situations where early-binding is
impossible, or where you have a desire for a more flexible API that
late-binding would provide.
>
Pete

[Peter Morris]

Re: Questions about Coding Practices

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]]

Re: Questions about Coding Practices

On Jul 14, 10:00 am, "Chakravart hy" <dskch...@msn.c omwrote:

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]

Re: Questions about Coding Practices

On Jul 14, 9:11 am, wangdaix...@gma il.com wrote:

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 <includeeleme nt 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]

Re: Questions about Coding Practices

Jon Skeet [C# MVP] <skeet@pobox.co mwrote:

On Jul 14, 10:00 am, "Chakravart hy" <dskch...@msn.c omwrote:

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.

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.

--
J.B. Moreno

[Peter Duniho]

Re: Questions about Coding Practices

On Mon, 14 Jul 2008 03:20:25 -0700, Pavel Minaev <int19h@gmail.c omwrote:

[...]

>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 start at
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
programming topics generally. Thanks for the link Pavel!

Pete

[wangdaixing@gmail.com]

Re: Questions about Coding Practices

On Jul 17, 9:44 am, "Peter Duniho" <NpOeStPe...@nn owslpianmk.com>
wrote:

On Mon, 14 Jul 2008 03:20:25 -0700, Pavel Minaev <int...@gmail.c omwrote:

[...]

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  programmingtopi cs 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#.