|
as Joseph Webster mentioned in his comment[^], "one school" tries to ban commentation completely, and write full self-explainatory code instead.
And I agree with you both, that such can't always be achieved - in the real world Code cannot always be that self-explainatory.
Not always, but often it can!
And in such cases I am of "one school" - means: When code explains itself, then commentation disimproves it.
Applied to your sample, I would not explain in the comment, that GetInstance() gets an Instance.
Because a Programmer, who can't read that from the code itself, should not be allowed to read it at all
Instead of that I would express another Must-Know about the Function more clearly, namely whether it can fail, and what will happen then.
So my comment of your Function would come out as:
public virtual T GetInstance<T>()
where T : IService
{ (While I assume, the Function is located in a class (self-explainatory) named as "ServiceManager" or something similar.)
What I want to say: Your 3 Questions are wonderful and of category "mustbe satisfied".
But additionally I recommend to focus Commentation very strong only on the non-self-explainatory parts of code.
modified 14-Jan-16 7:26am.
|
|
|
|
|
Most programmers ignore the "why" part, the comment.
It's not that the programmer doesn't want to write comment, it is that the programmer does not know how to write the comment. If every programmer keeps the "why" question in mind, he can write a clean comment, which leads to a clean function.
Actually I also like the criteria to decide if another function is needed, it's also helpful.
|
|
|
|
|
The premise is spot on. Bravo for that. This comment (sic) is about comments.
One school of thought holds that comments should be avoided entirely. If you need a comment to understand the code, then it needs to be refactored or improved.
That said, clearly all interfaces and APIs should be well documented and generating those docs from comments is the only way to go because if you don't keep comments updated then people can't use your stuff.
I question the use of comments on every function because we've all had the lovely experience of trying to maintain code where the initially well-intended (or mandated) comments are so stale as to be worse than useless. So unless you are running a doc generator (e.g. Sandcastle or doxygen) as part of your build process and reviewing the resulting docs, then don't bother with anything other than in-line comments. And those should be used more in unit tests than code.
|
|
|
|
|
Joseph Webster, CISSP wrote: One school of thought holds that comments should be avoided entirely.
I find that to be a bit extreme, because it falls apart when, while taken by themselves, the functions might be clear enough, but what's missing is the general thought of what the whole algorithm is doing. Having worked on complicated end-of-life analysis for switch rings on satellites, I can definitely say that comments, especially for code that is handling edge cases (including how to create the edge case), and comments describing the general algorithm, are essential.
Joseph Webster, CISSP wrote: I question the use of comments on every function because we've all had the lovely experience of trying to maintain code where the initially well-intended (or mandated) comments are so stale as to be worse than useless.
True - as I practice swallowing my own medicine, I find often enough that a well named function and parameters are more than sufficient to describe the function's what/how/why, especially when functions are reduced to just a few lines of code. When higher level functions reduce down to essentially a workflow of calling other functions, the code becomes very clear.
Thanks for your comments!
Marc
|
|
|
|
|
When using generics I always give my 'T' parameters proper names too, this helps when you have multiple Type parameters. this way you can also understand what 'T' is without having to check its constraints. eg:
public virtual TService GetInstance<TService>()
where TService : IService
{
VerifyRegistered<TService>();
VerifyInstanceOption<TService>();
IService instance = CreateInstance<TService>();
instance.Initialize(this);
return (TService)instance;
}
|
|
|
|
|
|
Function writing style is important, with consistency at the top of the list. I use:
/*****
Purpose: this function...
Paramter list:
int value this is...
Return value:
int 0 means failure, 1 is successful
*****/
int MyFunction(int value)
{
Using this format, I wrote a utility that looks for "/*****" and then copies to the opening paren of the function body. Using __FILE__ and __LINE__ you can create a function description document automatically from your code listings.
Second, a function name should tell what the function does, not how. The internal workings of the function should be a black box to the user. For example, StringSearch() is a better name than BoyerMooreSearch(), since the latter makes you "lie" to the user if you implement a new algorithm. Either that or you break their code by changing the function name.
Third, a function should be cohesive. That is, it should perform one task well. If you cannot explain what the function does in one or two sentences, it's probably not cohesive and should be broken apart. New programmers tend to write Swiss Army Knife functions which do multiple things using a long parameter list. Almost always a bad idea.
Finally, the function should not be coupled to another function. That is, don't write one function that assumes some dependent relationship to another function. Sometimes this cannot be avoided (e.g., with files open() is normally called before read() or write()), but try to avoid it if possible.
|
|
|
|
|
"wherefore", "what", "how", "why so and not otherwise" are four questions to any function (class/method/module) before its creation.
|
|
|
|
|
Could you explain a little bit on "wherefore"?
|
|
|
|
|
|
Good Tips. Actually i am looking this kind of best code practice and please share us more tips to do best code
|
|
|
|
|
Nice start to what I believe is a very big subject.
Every day, thousands of innocent plants are killed by vegetarians.
Help end the violence EAT BACON
|
|
|
|
|
|
My Vote of 5ed.
Small and Effective ..
Thanks..
|
|
|
|
|
Marc says, "Go forth and code better."
What he meant to say was, "Use Forth and your code will be automatically better."
|
|
|
|
|
XML Documentation should never be ambiguous or 'guess-work'.
"The user can get an instance of a service implementing the specified interface, but only if the service is registered as supporting instance creation." is in my opinion not a good summary for your function. Especially the word 'can' strikes me wrong.
Also, the summary should not be describing what the user can do, but what the function/method does.
"Verifies whether the given type has been registered and (something instanceoption), and returns a newly created and initialized instance." (Adapt to context.) Your summary basically told me nothing about what I can expect from the function, but was twice as long.
Just my 2cts.
|
|
|
|
|
I really appreciate the feedback!
wvdhouten wrote: Also, the summary should not be describing what the user can do, but what the function/method does.
I used to think that, and then I realized when I read API documentation, I pretty much rely on the name of the function to tell me what it does, but I'm usually guessing at why the function exists -- what was the author's intention for exposing this function? Yeah, in 90% of the cases, it's obvious, but here's a typical example from a document on ActiveX methods for an ATM:
Function: OpenDevice
Description Open the serial port for the card reader.
OK, that's sort of useless to me. I already know that the devices use serial ports. I'm more interested in "why" I need to open the device -- why doesn't this happen automatically if the device isn't already opened, etc. Here I'm nitpicking, but it illustrates bad documentation, IMO.
wvdhouten wrote: Especially the word 'can' strikes me wrong.
Agreed, I'm still learning the art of "why", hahaha.
Marc
|
|
|
|
|
(Sorry if this response is not so fancy with quotes and stuff. I'm not so adept in codeproject community-ing yet.)
I get what you're saying and agree that it would sometimes be very pleasant to understand the developer's motives, but would suggest that "Summary" is then the wrong place. I would assume it to be the summary for the method, not the summary for the developer's brain dump, so to say.
Information regarding prerequisites or a flow of methods, I would expect to be in either the 'Getting started' of the product, or possibly other tags in the XML doc, like for instance the "Remarks" element. That is, if the information is relevant to be exposed. When it's for other developers, I'd be totally happy with reading the 'why' in the inline comments.
In your example, I would say the "Summary" for the method was spot on, and should for instance include an "Exception" element if the function would throw an exception if the device is not opened on forehand. Or maybe use the "Remarks" element as for 'why'. <remarks>Closed or unopened devices may cause exceptions when interacted with.
I mean, I am not saying I am right either. A lot of it is not really standard and comes down to personal taste. So as I said, it was mainly my 2cts. Thanks for your feedback too by the way! Always pleasant to read theories on these things.
One of my friends sometimes call me pedantic on semantics, I suppose I'm starting to understand him now.
|
|
|
|
|
Oh and a short elaboration. The XML Documentation is the part that gets exposed when the code is made into a library and the code itself is no longer visible to the developer using the library. So as soon as you wrap up that DLL, the "what" and "how" are no longer available (Granted, the how is not important in a black box).
|
|
|
|
|
Agree. That is the first though that came to my mind. The rest is perfect!
|
|
|
|
|
5ed; Marc, you nailed it again! Keeping it in a simple, "www" notation is much better to teach others to write a good code.
I would recommend that you actually write a List<Tip></tip> about these good approaches too. I mean, it'd be a great way to share the minor hints, tips and experience with juniors, like me.
|
|
|
|
|