|
... in an alien landscape. All seems strange and displaced, as if I have become detached from reality. Nothing is where it should be. Nothing is when it should be. I am alone in a .... eh? What? What do you mean they just put the clocks forward last night, that's all?
I am not a number. I am a ... no, wait!
|
|
|
|
|
You are in a maze of twisty passages, all alike.
If you have an important point to make, don't try to be subtle or clever. Use a pile driver. Hit the point once. Then come back and hit it again. Then hit it a third time - a tremendous whack.
--Winston Churchill
|
|
|
|
|
A little dwarf just walked around a corner, saw you, threw a little axe at you (which missed), cursed, and ran away.
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
|
|
|
|
|
XYZZY
...just in case.
- I would love to change the world, but they won’t give me the source code.
|
|
|
|
|
Plugh 
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
|
|
|
|
|
<\nostagliatrip>
Ho Hum. Back to today's reality!
- I would love to change the world, but they won’t give me the source code.
|
|
|
|
|
Quote: What do you mean they just put the clocks forward last night, that's all?
No! That's not all. That stuff you're smoking has a lot to do with it! 
Get me coffee and no one gets hurt!
|
|
|
|
|
Last night? No it was three days ago! You may have sleep over...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
Maybe you've been listening to my Song of the Week a little too much for the past few days 
|
|
|
|
|
I've been in another reality ever since I had a stroke a year and a half ago. I didn't plan on taking a year and a half unpaid vacation, honest!!
CQ de W5ALT
Walt Fair, Jr., P. E.
Comport Computing
Specializing in Technical Engineering Software
|
|
|
|
|
Today, whilst exploring deep comparison of .NET objects (nested-in-nested Types), I came across this remarkable open source library that uses reflection to compare object instances (recursive is an option, among many options).
Greg Finzer's CompareObjects [^].
This library does everything but walk the dogs, and the source is, imho, beautifully organized, structured, commented. Highly recommended reading, if you like reading good code: the different classes for comparing objects of various types in: \Compare-Net-Objects-master\Compare-NET-Objects\TypeComparers. What a delight to read code like this:
public List<string> MembersToIgnore { get; set; }Of course, there's equally great code here in CP articles !
In my fairly long (and very odd) pilgrim's progress through the digital world, I can't remember anything like the wealth of high-quality code that exists today ... prior to ten years ago.
Me thankful 
cheers, Bill
«The truth is a snare: you cannot have it, without being caught. You cannot have the truth in such a way that you catch it, but only in such a way that it catches you.» Soren Kierkegaard
modified 27-Mar-16 9:31am.
|
|
|
|
|
Not sure if you're being sarcastic  Not only do those comments not follow Microsoft guidelines, I don't think they're particularly good.
|
|
|
|
|
No, I'm not being sarcastic; if I was being sarcastic, you would feel the sharp point of it entering your eye.
Of course, you are entitled to your opinion on the commenting, but, I would ask you if you have actually read enough of the code to form an opinion rather than "rushed to judgement" based on a single example from such a faulty source as this flea on the hide of C# who dares write like he knows what from what.
I admit I am used to reading code that is often butt-naked of comments; perhaps I am grateful for what may seem, by your exalted standards, mere "crumbs"
I look forward to studying your next CP article, and seeing how you do commenting ... that's not sarcastic, either. I am always ready to learn from good examples.
cheers, Bill
«The truth is a snare: you cannot have it, without being caught. You cannot have the truth in such a way that you catch it, but only in such a way that it catches you.» Soren Kierkegaard
|
|
|
|
|
If you're used to code with no comments then for sure these are better than nothing, but I stand by my comments that they're not very good and don't follow guidelines. If you were to use that code in a project that uses style analysis tools you've have to re-write the comments.
As for comments in CP articles, you don't comment articles the same way you would comment actual code. Also those particular comments are for people who implement the code mainly as an API, eg they need to know what the function does without access to the source code to determine it for themselves, and those comments can be used to generate "MSDN" documentation and they are also used in Intellisense etc.
I haven't looked through the whole code, but I am assuming that you chose what you considered to be a good example to use in your thread so I don't think it's unjust of me to judge the rest of the code based on the snippet you provided.
|
|
|
|
|
F-ES Sitecore wrote: I haven't looked through the whole code, but I am assuming that you chose what you considered to be a good example to use in your thread so I don't think it's unjust of me to judge the rest of the code based on the snippet you provided.
If you question my ability to know what good comments are (and, that's a very fair question), then why would you assume my selected comment accurately describes the quality of the comments in a work by another person which you haven't bothered to peruse ?
If you wish to present yourself as a judge of good commenting, rather than just a drive-by sniper taking cheap-shots, you need to investigate the source with your own eyes. Of course, that would take effort on your part.
«The truth is a snare: you cannot have it, without being caught. You cannot have the truth in such a way that you catch it, but only in such a way that it catches you.» Soren Kierkegaard
|
|
|
|
|
I don't think it's unreasonable to assume that if you are saying something is well commented that you would use an example that you consider to be well commented. You stated in your OP you think this is well commented, and I am simply telling you that in my opinion it isn't. That is part subjective, I don't think the person who wrote those comments has English as a first language so they don't read well for me, but it is also part objective as they don't follow Microsoft's guidelines. If I look at the help for, say, the Connection property of SqlCommand then look at the help for this code they are completely different in style, and they should be the same, you shouldn't expect your audience to adapt, that is what guidelines are there for.
If you can find a better example that will make me change my mind then by all means find one and update your OP.
|
|
|
|
|
BillWoodruff wrote: If you question my ability to know what good comments are
But that's not what he's saying, at all.
He's saying that the comments, as written, do not follow guidelines, so would be picked up by style analysis tools -- which, given the <summary> tags, may well be in use.
However, I would have thought that you would have picked up the incorrect use of "or" in the first line of the summary, which gives the sentence a meaning that the writer probably does not intend.
That's two strikes. Your venomous response in your last posting counts as a third, for me. You were not being attacked; someone was discussing something with you.
Discussing: you know, where one person gives his opinion, and other people give theirs, and everyone respects other people's rights to have opinions (or, at very least, responds with a riposte that is witty, not nasty).
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
Writing good comments is a skill that is often lacking in programmers. Too often you see meaningless comments like:
i++;
Any idiot can see you are incrementing i! The comment is meaningless. Meaningless comments is one of my pet peeves.
Get me coffee and no one gets hurt!
|
|
|
|
|
Cornelius Henning wrote: Any idiot can see you are incrementing i!
Well, yeah. But it's intelligent people that need the help!
I am not a number. I am a ... no, wait!
|
|
|
|
|
I agree about silly comments, but sometimes
while(x)
{
...
i++;
it simply helps to "give a nice Format"
Only my mind
modified 19-Jan-21 21:04pm.
|
|
|
|
|
Right? I will never not
while is_cool():
#...
else: #nobreak
#...
and
try:
#...
except:
pass
else: #noraise
#...
Sure, anyone experienced will know what's going on, but I'm guaranteed to forget the next time I come to it.
|
|
|
|
|
I don't mind that kind of comment if it's in DoxyGen tags, or similar, because otherwise the HTML documentation would be blank for that function, but in-line like that it's a waste of time to both write and read.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
BillWoodruff wrote: This library does everything but walk the dogs
No good to me then!
I am not a number. I am a ... no, wait!
|
|
|
|
|
I completely agree. I used this library couple of years back and was delighted to see it work straightaway along with a very good code quality and equally good comments.
All are born right-handed. Only gifted few overcome it.
There's NO excuse for not commenting your code.
|
|
|
|
|
If one person on this thread ignores the static (mine and others), and gives the author of this incredible library the credit he's due ...
I think I'll go on living: no matter that enthusiasm, here, often requires the bearer to suffer the "slings and arrows of outrageous fortune"
cheers, Bill
«The truth is a snare: you cannot have it, without being caught. You cannot have the truth in such a way that you catch it, but only in such a way that it catches you.» Soren Kierkegaard
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
