On Sun, 13 Jul 2008 22:11:48 -0700, <wa*********@gmail.comwrote:
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.
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
