Programmers should not be allowed to, well, program.

[agolddog]

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.

[RafagaX]

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...

[mrchief_2000]

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
  end

or this one:

  def show\_readme
    readme 'README' if behavior == :invoke
  end

This 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?

[Nathan Nowak]

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

[patbob]

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.

[bryce]

mrchief_2000 wrote:

I know Marc's reputation, so obviously he's seeing something that I don't. So what am I missing?

I reckon hes turning into a grumpy old man, he'll move out near Wogger's place soon. bryce

MCAD ---

[Mycroft Holmes]

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

[Stefan_Lang]

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

[Lost User]

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')

[Marc Clifton]

_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

Unit Testing Succinctly