|
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
|
|
|
|
|
I couldn't agree more I doing some work involving RabbitMQ and Protocol Buffers developed in Java using intelliJ (which is bloody amazing by the way and I've always been a Visual Studio chap) and everything so far has been free, gratis, zilch cost! How are people making money I wonder.
|
|
|
|
|
Quote: recursive is an option, among many options
I like how this sounds.
|
|
|
|
|
People who don't like to write comments figure comments are useless unless they rival Shakespeare sonnets in beauty and depth. People who do write comments know that commenting the code helps both the author and any readers to understand intent. Further, while a particular comment may be somewhat obvious, the effort made over the whole program to review and summarize its pieces is a mental discipline that generally pays off in better code.
|
|
|
|
|
SeattleC++ wrote: a mental discipline that generally pays off in better code.
A very eloquent comment, and a very solid finish !
I believe there are some very interesting developments in annotating code ... thinking of writing comments in the code as one form of annotation ... still to come, though I don't claim to know what they will be.
People I've encountered who don't like to write comments have been either just unaware/uninformed of their future value, or ... lazy. However, there are rare people with phenomenal mnemonic skills; I met a fellow at a Mac software company in the late 1980's whose co-workers called him "Mr. Rom," because he knew, from memory, all the op codes for every ROM function call.
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
|
|
|
|
|
|
Well, when a Mommy Chocolate Parrot and a Daddy Bee want to have babies, they get together under a Gooseberry Bush and Summon The Stork, who delivers them a load of Chocolate Eggs, which they take turns in hatching.
These days, the Stork's job has been outsourced, the Chocolate Parrot died of Avian Flu, and the Chocolate Bee was downsized - so Tesco fills all three roles and loads its shelves with Chocolate Eggs for all to take home and hatch. The Easter Bunny drives the truck.
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
|
|
|
|
|
This is one of your best, Griff 
«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
|
|
|
|
|
Anti human control freaks Monsanto are killing all the bees intentionally so you are forced to buy their centric ally engineered plants. And keep buying them year after year 
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
