Blinded by Open Source Quality
-
Writing good comments is a skill that is often lacking in programmers. Too often you see meaningless comments like:
i++; // increment 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!
-
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.
-
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
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++; // increment 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!
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!
-
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:
/// <summary>
/// Ignore Data Table Names, Data Table Column Names, properties, or fields by name
/// during the comparison. Case sensitive. The default is to compare all members.
/// </summary>
/// <example>MembersToIgnore.Add("CreditCardNumber")</example>
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
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.
-
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
-
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:
/// <summary>
/// Ignore Data Table Names, Data Table Column Names, properties, or fields by name
/// during the comparison. Case sensitive. The default is to compare all members.
/// </summary>
/// <example>MembersToIgnore.Add("CreditCardNumber")</example>
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
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.
-
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:
/// <summary>
/// Ignore Data Table Names, Data Table Column Names, properties, or fields by name
/// during the comparison. Case sensitive. The default is to compare all members.
/// </summary>
/// <example>MembersToIgnore.Add("CreditCardNumber")</example>
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
Quote:
recursive is an option, among many options
I like how this sounds.
-
Not sure if you're being sarcastic :confused: Not only do those comments not follow Microsoft guidelines, I don't think they're particularly good.
-
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:
/// <summary>
/// Ignore Data Table Names, Data Table Column Names, properties, or fields by name
/// during the comparison. Case sensitive. The default is to compare all members.
/// </summary>
/// <example>MembersToIgnore.Add("CreditCardNumber")</example>
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
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.
-
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
-
I agree about silly comments, but sometimes
while(x)
{
// Do this and that
...// Do the next
i++;it simply helps to "give a nice Format" Only my mind :)