Programmers should not be allowed to, well, program.
-
Eddy Vluggen wrote:
code comments aren't worth it as their code is self documenting
Well I can vouch for that. Not that it is true but that it seems to be going in that direction. I was looking at Uncle Bob's clean code videos the other day and he also proclaims commenting to be no need. BUT, if one is not going to comment then yes, your classes and methods should be named as such to explain what it does in merely its name. It seems code is the one of a very few trades where it is apparent that change is the only constant :-)
-
On more than one occasion I have been flummoxed Here's an example of class naming. There were some view model classes called QuickFindThenAssignToxxxxxxViewModel Which performed a search for the user then sent a message with the results to a particular entity (the xxxxxxx) Now, forget the fact that this is more complex than it should be and less flexible than it needs to be, at some point the dev decided that a class name of QuickFindThenAssignToCustomerViewModel would be too verbose, so started calling the class QuickFindThenAssignToCViewModel instead (I hope he never wants to look up Clients!) But finally laziness took hold entirely the resource class I needed to check out was called QFTA2SAVResource I still don't know what SAV is...
MVVM # - I did it My Way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
A SAV is a red coloured sausage made from unknown indiscriminate matter which is usually served on an elongated bread role with sauce or simply battered and deep fried.
"Rock journalism is people who can't write interviewing people who can't talk for people who can't read." Frank Zappa 1980
-
For example.[^] OK, it works - and it seems to work quite well. And I'm not wanting to criticize the hard work this fellow put into this package, far from it actually, it simply makes for a good example of why I groan, sigh, and generally feel like we have a lot of room to grow. There isn't a single comment that I've found in the code. The documentation on the home page is, well, sort of sufficient but not quite. There are no examples. Found examples elsewhere, and also poorly written with at least one glaring bug. The best example I found was simply another github application, again with no documentation -- the fellow couldn't even take the time to change the boilerplate text that github generates when you create a project -- but it was as basic an example as necessary. Good enough. This isn't really a rant, it's more about the overall lack of quality in what people put up there for general consumption. Now, don't get me wrong, I'm very appreciative of the fact that I can take advantage of other people's hard work for free. And I suppose that's the point, it's free, so don't look a gift horse in the mouth, right? And gee Marc, it's open source, so if you want comments, contribute back to the project! Riiight. I think the issue for me is I'd like programmers to realizing that, if you're going to post something for the community at large to use, I for one would really appreciate it if the job was done with same professionalism as if you'd gotten paid to do the work. Oh wait, I see the error in my ways... :sigh: You might ask, why do I want documentation and code comments? Well, documentation so I don't spend 3 hours doing something that should take 30 minutes. Code comments so that I can learn from others - most of this stuff is foreign to me and I was hoping to learn some cool things without having to dissect the code. P.S - and the reason I use the term "programmer" is that this is an example of the kind of code and documentation I guess I expect from a "programmer", whereas I have a higher standard for "developer", and even higher for "software engineer". Marc
I think I've figured out the problem, Marc. You think open source should be developed with the same care professional software is developed, where the word 'professional' means 'paid'. Open source must be free! Making a profit from your labor is abhorent, at least according to Richard Stallman(*) :rolleyes:. (*) At least I didn't call him The Great Satan, like I was tempted to.
Software Zen:
delete this; -
But we all know that if you decide to publish and therefore start commenting and documenting your code it turns into a major effort. You find bugs, you suddenly wonder why you did something this way instead of that way. It is much easier just to dump your code into something like github and ignore it. You are describing the difference between open source and CP, here your crap is reviewed and the therefore the quality is somewhat higher and that is the reason CP is so valuable.
Never underestimate the power of human stupidity RAH
Excellent point. CP does create a sort of peer review mechanism.
Software Zen:
delete this; -
But we all know that if you decide to publish and therefore start commenting and documenting your code it turns into a major effort. You find bugs, you suddenly wonder why you did something this way instead of that way. It is much easier just to dump your code into something like github and ignore it. You are describing the difference between open source and CP, here your crap is reviewed and the therefore the quality is somewhat higher and that is the reason CP is so valuable.
Never underestimate the power of human stupidity RAH
Interesting point. I'd never considered CP in that way before but you are right – if you post rubbish here you'll know about it and either fix it or take it down, so the standard of what ends up being available is quite high. My own articles have had corrections to both article and code thanks to people pointing out mistakes.
-
Marc Clifton wrote:
There are no examples.
From that site's Wiki
"Here is an example which speaks for itself:"
I actually agree with you in many cases - but in this case there seems to be quite a lot of documentation and (brief) usage examples - much more than I've seen on many a page. And no code comments? Judging by the younger programmers I work with, we need to get used to it, because they honestly believe code comments aren't worth it as their code is self documenting... which leads neatly back to the subject of your post :)
MVVM # - I did it My Way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
_Maxxx_ wrote:
From that site's Wiki
"Here is an example which speaks for itself:"
The fact that I cannot find this on the site's wiki (nor does it come up when I google for it) means something. Not sure what. :~ Marc
-
Marc Clifton wrote:
Riiight. I think the issue for me is I'd like programmers to realizing that, if you're going to post something for the community at large to use, I for one would really appreciate it if the job was done with same professionalism as if you'd gotten paid to do the work.
The problem is that is probably the same quality they put out at work?
VS2010/Atmel Studio 6.1 ToDo Manager Extension The problem with the gene pool is that there is no lifeguard. -Steven Wright
Mike Hankey wrote:
The problem is that is probably the same quality they put out at work?
Probably! :) Marc
-
For example.[^] OK, it works - and it seems to work quite well. And I'm not wanting to criticize the hard work this fellow put into this package, far from it actually, it simply makes for a good example of why I groan, sigh, and generally feel like we have a lot of room to grow. There isn't a single comment that I've found in the code. The documentation on the home page is, well, sort of sufficient but not quite. There are no examples. Found examples elsewhere, and also poorly written with at least one glaring bug. The best example I found was simply another github application, again with no documentation -- the fellow couldn't even take the time to change the boilerplate text that github generates when you create a project -- but it was as basic an example as necessary. Good enough. This isn't really a rant, it's more about the overall lack of quality in what people put up there for general consumption. Now, don't get me wrong, I'm very appreciative of the fact that I can take advantage of other people's hard work for free. And I suppose that's the point, it's free, so don't look a gift horse in the mouth, right? And gee Marc, it's open source, so if you want comments, contribute back to the project! Riiight. I think the issue for me is I'd like programmers to realizing that, if you're going to post something for the community at large to use, I for one would really appreciate it if the job was done with same professionalism as if you'd gotten paid to do the work. Oh wait, I see the error in my ways... :sigh: You might ask, why do I want documentation and code comments? Well, documentation so I don't spend 3 hours doing something that should take 30 minutes. Code comments so that I can learn from others - most of this stuff is foreign to me and I was hoping to learn some cool things without having to dissect the code. P.S - and the reason I use the term "programmer" is that this is an example of the kind of code and documentation I guess I expect from a "programmer", whereas I have a higher standard for "developer", and even higher for "software engineer". Marc
I think some of it is experience. People how haven't been coding that long don't have the experience of looking at their own (much less someone else's) code they wrote six months ago and thinking "WTF was I doing again?" Once you've done that a few times, you learn (one hopes) to put comments in spots which were tough to get going, or where you chose a design/implementation out of several pretty equal ideas. The other facet of experience is realizing when what you're building is functional, but just doesn't feel great. Maybe the light bulb doesn't go on for you about how to refactor, or you simply don't have the requisite knowledge of the "righter" approach, but putting comments in that "there's got to be a better way, but I can't think of it right now, here's what I'm doing" should help. All in all, I believe we've got to learn to create the philosophical documentation as much than the technical. By that I mean, explaining what you wree thinking when you chose a particular implementation. Most people can read the code and tell you what it is doing; it's not always obvious what you intended for it to do.
-
For example.[^] OK, it works - and it seems to work quite well. And I'm not wanting to criticize the hard work this fellow put into this package, far from it actually, it simply makes for a good example of why I groan, sigh, and generally feel like we have a lot of room to grow. There isn't a single comment that I've found in the code. The documentation on the home page is, well, sort of sufficient but not quite. There are no examples. Found examples elsewhere, and also poorly written with at least one glaring bug. The best example I found was simply another github application, again with no documentation -- the fellow couldn't even take the time to change the boilerplate text that github generates when you create a project -- but it was as basic an example as necessary. Good enough. This isn't really a rant, it's more about the overall lack of quality in what people put up there for general consumption. Now, don't get me wrong, I'm very appreciative of the fact that I can take advantage of other people's hard work for free. And I suppose that's the point, it's free, so don't look a gift horse in the mouth, right? And gee Marc, it's open source, so if you want comments, contribute back to the project! Riiight. I think the issue for me is I'd like programmers to realizing that, if you're going to post something for the community at large to use, I for one would really appreciate it if the job was done with same professionalism as if you'd gotten paid to do the work. Oh wait, I see the error in my ways... :sigh: You might ask, why do I want documentation and code comments? Well, documentation so I don't spend 3 hours doing something that should take 30 minutes. Code comments so that I can learn from others - most of this stuff is foreign to me and I was hoping to learn some cool things without having to dissect the code. P.S - and the reason I use the term "programmer" is that this is an example of the kind of code and documentation I guess I expect from a "programmer", whereas I have a higher standard for "developer", and even higher for "software engineer". Marc
Well, most open source projects are "I made this that find helpful, if you find it helpful great", so i never expect high quality documentation, although I expect at least an example or two of usage so I can figure out how to use it without reading the code. But when I have to modify the source of a project for whatever reason, then I expect either to the code the be self documenting (or pretty obvious) or that it include comments, an example of the former is Mono.Cecil, their code is not documented at all, no docs, no comments, nothing, yet it's easy to follows and in most cases obvious what it does.
CEO at: - Rafaga Systems - Para Facturas - Modern Components for the moment...
-
For example.[^] OK, it works - and it seems to work quite well. And I'm not wanting to criticize the hard work this fellow put into this package, far from it actually, it simply makes for a good example of why I groan, sigh, and generally feel like we have a lot of room to grow. There isn't a single comment that I've found in the code. The documentation on the home page is, well, sort of sufficient but not quite. There are no examples. Found examples elsewhere, and also poorly written with at least one glaring bug. The best example I found was simply another github application, again with no documentation -- the fellow couldn't even take the time to change the boilerplate text that github generates when you create a project -- but it was as basic an example as necessary. Good enough. This isn't really a rant, it's more about the overall lack of quality in what people put up there for general consumption. Now, don't get me wrong, I'm very appreciative of the fact that I can take advantage of other people's hard work for free. And I suppose that's the point, it's free, so don't look a gift horse in the mouth, right? And gee Marc, it's open source, so if you want comments, contribute back to the project! Riiight. I think the issue for me is I'd like programmers to realizing that, if you're going to post something for the community at large to use, I for one would really appreciate it if the job was done with same professionalism as if you'd gotten paid to do the work. Oh wait, I see the error in my ways... :sigh: You might ask, why do I want documentation and code comments? Well, documentation so I don't spend 3 hours doing something that should take 30 minutes. Code comments so that I can learn from others - most of this stuff is foreign to me and I was hoping to learn some cool things without having to dissect the code. P.S - and the reason I use the term "programmer" is that this is an example of the kind of code and documentation I guess I expect from a "programmer", whereas I have a higher standard for "developer", and even higher for "software engineer". Marc
Most of the code is actually self documenting (I'm excluding code /vendor assuming that's not his). For example
def copy\_locale if Gmaps4rails.pipeline\_enabled? directory assets\_source\_path, assets\_destination\_path copy\_file "../../../public/stylesheets/gmaps4rails.css", "vendor/assets/stylesheets/gmaps4rails.css" else %w( base google openlayers bing ).each do |filename| copy\_file js\_source\_path(filename), js\_destination\_path(filename) end copy\_file "../../../public/stylesheets/gmaps4rails.css", "public/stylesheets/gmaps4rails.css" end endor this one:
def show\_readme readme 'README' if behavior == :invoke endThis reads like plain english and is quite evident what the code is doing, and even though I'm not a ruby programmer, I can understand most of it. This is true for almost all of his codebase. I know Marc's reputation, so obviously he's seeing something that I don't. So what am I missing?
-
But we all know that if you decide to publish and therefore start commenting and documenting your code it turns into a major effort. You find bugs, you suddenly wonder why you did something this way instead of that way. It is much easier just to dump your code into something like github and ignore it. You are describing the difference between open source and CP, here your crap is reviewed and the therefore the quality is somewhat higher and that is the reason CP is so valuable.
Never underestimate the power of human stupidity RAH
Mycroft Holmes wrote:
You are describing the difference between open source and CP, here your crap is reviewed and the therefore the quality is somewhat higher and that is the reason CP is so valuable.
I may be willing to concede that the quality of code in an average CP article is higher than that of a randomly selected open source project but I don't think that's what makes CP so valuable. Honestly, with the 10 million member celebration I've been thinking about whether CodeProject is still relevant after all these years and what exactly is its purpose or mission. I've been having trouble coming up with positive answers to these questions. Judging by some of the other comments CP might be valuable mostly to authors. It seems to serve as a one stop place to have your code thoughtfully peer reviewed. However, as a place to find code to use in your own projects or as a place to learn about coding in general, I'm somewhat skeptical. I frequently make use of code from Stack Overflow and open source projects but I can not think of a single instance where I have used CP code in any of my software. In all fairness, the lack of utility I've found may have more to do with the fact that CP is C# focused, I haven't programmed in C# in years, rather than because it lacks in any objective measure of value. However, my point is that quality does not equal value. In this case, CP failed to even attempt to address the problem Marc had. We all hate software managers who push quantity over quality but next to infinite loops the biggest bottleneck in any piece of software is the code that isn't written. As long as it takes more time to write high quality code than low quality code and the demand for code outstrips the supply we are doomed to be awash in a sea of poor code. This seems completely unrelated to whether or not we can see those errors because the code is open source. Perhaps I misread, but I detected a note of animosity towards open source in your reply. Maybe like many you are afraid that open source software will steal your lunch. Maybe you have every right to be angry because open source software ate your baby. Regardless of whether your reaction is justified I think you are making an unfair comparison in this case. You are comparing a single open source project in its fledgling stages to CP, a mature community which has been in existence for twelve years and now has ten million members. If you look at the code of an open source project of a simila
-
For example.[^] OK, it works - and it seems to work quite well. And I'm not wanting to criticize the hard work this fellow put into this package, far from it actually, it simply makes for a good example of why I groan, sigh, and generally feel like we have a lot of room to grow. There isn't a single comment that I've found in the code. The documentation on the home page is, well, sort of sufficient but not quite. There are no examples. Found examples elsewhere, and also poorly written with at least one glaring bug. The best example I found was simply another github application, again with no documentation -- the fellow couldn't even take the time to change the boilerplate text that github generates when you create a project -- but it was as basic an example as necessary. Good enough. This isn't really a rant, it's more about the overall lack of quality in what people put up there for general consumption. Now, don't get me wrong, I'm very appreciative of the fact that I can take advantage of other people's hard work for free. And I suppose that's the point, it's free, so don't look a gift horse in the mouth, right? And gee Marc, it's open source, so if you want comments, contribute back to the project! Riiight. I think the issue for me is I'd like programmers to realizing that, if you're going to post something for the community at large to use, I for one would really appreciate it if the job was done with same professionalism as if you'd gotten paid to do the work. Oh wait, I see the error in my ways... :sigh: You might ask, why do I want documentation and code comments? Well, documentation so I don't spend 3 hours doing something that should take 30 minutes. Code comments so that I can learn from others - most of this stuff is foreign to me and I was hoping to learn some cool things without having to dissect the code. P.S - and the reason I use the term "programmer" is that this is an example of the kind of code and documentation I guess I expect from a "programmer", whereas I have a higher standard for "developer", and even higher for "software engineer". Marc
Marc Clifton wrote:
This isn't really a rant, it's more about the overall lack of quality in what people put up there for general consumption
You have too high of expectations for open source. In my experience, what you observe is typical.
We can program with only 1's, but if all you've got are zeros, you've got nothing.
-
Most of the code is actually self documenting (I'm excluding code /vendor assuming that's not his). For example
def copy\_locale if Gmaps4rails.pipeline\_enabled? directory assets\_source\_path, assets\_destination\_path copy\_file "../../../public/stylesheets/gmaps4rails.css", "vendor/assets/stylesheets/gmaps4rails.css" else %w( base google openlayers bing ).each do |filename| copy\_file js\_source\_path(filename), js\_destination\_path(filename) end copy\_file "../../../public/stylesheets/gmaps4rails.css", "public/stylesheets/gmaps4rails.css" end endor this one:
def show\_readme readme 'README' if behavior == :invoke endThis reads like plain english and is quite evident what the code is doing, and even though I'm not a ruby programmer, I can understand most of it. This is true for almost all of his codebase. I know Marc's reputation, so obviously he's seeing something that I don't. So what am I missing?
-
Mycroft Holmes wrote:
You are describing the difference between open source and CP, here your crap is reviewed and the therefore the quality is somewhat higher and that is the reason CP is so valuable.
I may be willing to concede that the quality of code in an average CP article is higher than that of a randomly selected open source project but I don't think that's what makes CP so valuable. Honestly, with the 10 million member celebration I've been thinking about whether CodeProject is still relevant after all these years and what exactly is its purpose or mission. I've been having trouble coming up with positive answers to these questions. Judging by some of the other comments CP might be valuable mostly to authors. It seems to serve as a one stop place to have your code thoughtfully peer reviewed. However, as a place to find code to use in your own projects or as a place to learn about coding in general, I'm somewhat skeptical. I frequently make use of code from Stack Overflow and open source projects but I can not think of a single instance where I have used CP code in any of my software. In all fairness, the lack of utility I've found may have more to do with the fact that CP is C# focused, I haven't programmed in C# in years, rather than because it lacks in any objective measure of value. However, my point is that quality does not equal value. In this case, CP failed to even attempt to address the problem Marc had. We all hate software managers who push quantity over quality but next to infinite loops the biggest bottleneck in any piece of software is the code that isn't written. As long as it takes more time to write high quality code than low quality code and the demand for code outstrips the supply we are doomed to be awash in a sea of poor code. This seems completely unrelated to whether or not we can see those errors because the code is open source. Perhaps I misread, but I detected a note of animosity towards open source in your reply. Maybe like many you are afraid that open source software will steal your lunch. Maybe you have every right to be angry because open source software ate your baby. Regardless of whether your reaction is justified I think you are making an unfair comparison in this case. You are comparing a single open source project in its fledgling stages to CP, a mature community which has been in existence for twelve years and now has ten million members. If you look at the code of an open source project of a simila
Actually you seem to have the wrong slant on what I was trying to get across. Marc was bitching about the quality of a single article, I was trying to make the point that we reduce the crap level via peer review at CP. CP is but a single source of code/support I use, product forums and SO get an excellent representation, SO probably more than most. I have code/snippets from many sources, probably more from CP than elsewhere (except Telerik who often supply projects as a solution). I was not comparing 1 OS project to CP, I was trying highlighting the difference in methodology for publishing. As for animosity - WAT, I tend to be a little crusty at the best of times, I think you may be a little too sensitive in you interpretation. I have no issue with OS, I have more work than I can do and have had for 20 years so I don't consider OS anything but a source of information with a high crap quotient. I read SF so I am used to a high crap quotient! I find I get the most value out of snippets and problem resolution code blocks (mostly on SO) and look to articles/blogs when I want a deeper understanding of a subject. As for the level of commenting, AFAIAC it must be high on a published article, you need to explain why as well as what you are doing. My production code has somewhat less :-O
Never underestimate the power of human stupidity RAH
-
On more than one occasion I have been flummoxed Here's an example of class naming. There were some view model classes called QuickFindThenAssignToxxxxxxViewModel Which performed a search for the user then sent a message with the results to a particular entity (the xxxxxxx) Now, forget the fact that this is more complex than it should be and less flexible than it needs to be, at some point the dev decided that a class name of QuickFindThenAssignToCustomerViewModel would be too verbose, so started calling the class QuickFindThenAssignToCViewModel instead (I hope he never wants to look up Clients!) But finally laziness took hold entirely the resource class I needed to check out was called QFTA2SAVResource I still don't know what SAV is...
MVVM # - I did it My Way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
I'm using very long variable and class names like in your first example* all the time, but I know even those are not enough to make a complex algorithm understandable. not even to myself when I look at my own code three months later. I'll add comments whenever there's an algorithmic twist that cannot be expressed by code style, variable names or other 'in-code-documentation'. And that encompasses quite a lot of my code. *: on a sidenote, you should give those programmers an editor with autocomplete functionality - VI just doesn't cut it nowadays ;P
-
_Maxxx_ wrote:
From that site's Wiki
"Here is an example which speaks for itself:"
The fact that I cannot find this on the site's wiki (nor does it come up when I google for it) means something. Not sure what. :~ Marc
-
Means you can't google very well? Try Here[^]
MVVM # - I did it My Way ___________________________________________ Man, you're a god. - walterhevedeich 26/05/2011 .\\axxx (That's an 'M')
_Maxxx_ wrote:
Means you can't google very well?
Oh, that one. Hahaha, yeah, saw that perusing the wiki. The example does not speak for itself - there's so much missing, like the model, the javascript, the HTML view... As far as an example goes of just the controller, it's decent enough. Marc