The amount of comments is difficult to balance and yes as you get more experience, you'd rather cram as much code lines in a screen shot as possible. 0 comments ? No that's not good. The other extreme he shows is also not viable. If maintaining the comments takes as much time as maintaining the code, productivity will inevitably suffer.
We need to find a balance; short function synopsis, critical code section comments, ... These should be the basis from which we write comments and should be readable without the code so you get a minimal comprehension of what the code does without having to read the code entirely. It does not mean however that it should replace the code when looking for the details. Anything else that transcends the code modules should be in an external document. The other subject of Steve's post is much more important than the part about comments. He's absolutely right about meta data overkill... and there's nothing funny about it when you look at the overall situation. If I look back at the Java code my team wrote in the last 4 years, there is less human generated code lines than meta data configuration lines and generated code lines from this meta data. Typically written in XML which is so cumbersome that you need a schema sensitive editor to create valid files... A task by itself that has nothing to do with coding. Are these XML configuration files really self describing ? The number of frameworks out there with their specific configuration weirdness makes transitions from one to the other at best awkward. As soon as you hit a major bug or want to do something that is not supported or does not fit in a framework you're left nude on the ice bank. If you have invested heavily in configuration files and not in the code so your options are limited and require significant investments. In the life of a project, it's not good... At least if you are using code libraries you can modify the code locally to circumvent the problem. With frameworks it's much more complicated to do, do you have access to the code ? Do you have resources to fix the issue without compromising the framework ? What about maintenance ? Can you expect your fix to make it in the next release or is it too specific to your project to ever make it in the general code base ?.... All these options are far from fixing a limited code chunk in a library. People have been less and less polyvalent in the last 10 years. Those lucky enough to work deep enough with different technologies should make sure they keep that skill and open mind. I feel things will eventually change because the industry track record has not improved at all with this bureaucratic approach to software. The industry tried to replace intelligence (coders creating effective code) by some fabrication process driven by robots (writing endless configuration lines to generate code, specify behaviour, ...) while the anarchitects and DBA model the universe down to the atoms... Meanwhile the project time lines and budgets are busted and the pertinence of the code delivered drops. I've seen projects where intensive modelling made the performance so unbearable that some extra time was added at the end of the project to get rid of some of the modelling to get back some performance. Some of these projects were killed because there was no way you could retool them to remove the performance bottlenecks without redoing the project. Too much modelling kills but it does not mean that you do not need a model, you have to know when to stop. But that's out of reach for most of the model addicts out there. You do not need a modelling tool to built a flexible model, you need a minimal set of rules to which your system should stick to avoid failures. The industry replaced this common sense by these heavy tools that created the trend that you should model everything to ensure the code is "right". Tools like Rationale are the worst, they pretend that you can create code from a model without hand crafting the code... I've seen code generated by these tools and it's basically unreadable. Things are broke down to 10 lines classes, there is no way you can really understand the code except if you understand fully the model and hence what the modeler had in mind. The industry has been seeking the Holy Graal to replace the coder by some formal bureaucratic process since the end of 1970's and what we have seen in the last 10 years is another failure to reach that goal. Bureaucracy cannot replace intelligence. We see this in our respective governments and how they "manage" public services so why would we expect a better outcome in creating software the same way ? Is this thread unpleasant ? Looking at the world without pink glasses is not funny but taking the time to understand things gives you a sense of where we come from and where we might be going. As for Steve's post, it's about serious matters. Nonetheless, have a Happy New Year :))) and sorry for the heavy post... Luc On Thu, 2009-01-01 at 09:32 -0600, Hugh Winkler wrote: > I hesitate to extend this unpleasant thread, but here's a relevant > post that definitely takes a stand on the commenting issue: > > http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.html > > As usual with Steve, it's a funny post, so I hope nobody takes it too > seriously :) > > Hugh > > > On Wed, Dec 31, 2008 at 9:49 AM, Tom Ayerst <tom.aye...@gmail.com> wrote: > > "'Redundant comments are useless' is the mantra of the dilettante, the > > amateur, and the cowboy."dilettante, the amateur, and the cowboy"", ouch. > > Redundant comments are... redundant (hence the name), and a support overhead > > and a source of misunderstanding if they are not updated in line with the > > code. If you are writing code that will be read by people familiar with the > > language and idioms and using meaningful names then a small number well > > targeted comments are usually enough (Personally I do like a comment on each > > function saying what it is for, doc strings look like the right solution for > > this). > > > > Having said that; redundancy is a matter of context and I could use more > > comments and meaningful variables in example code, I am acquainted with > > Scheme so I can work my way through, but it is easy to get lost in the > > homogeneous syntax and unfamiliar constructs and idioms. > > > > When trying something new the fewer gumption traps the better and it is > > important to make sure information is to hand, this could be done through > > repetition or by the application of a little more indirection; earlier in > > the thread Mark asked if people would be aware of how to set up a clj > > script, good question and a link to the place that explains how, when you > > need it, would be very useful. > > > > Personally I don't think we need standards and stuff, what we need is some > > more "code with training wheels" (lots comments and links taking you through > > it very gently). That is not really Rich's job, he is to busy inventing the > > thing, I think Mark's evolving example is great and a few more like it > > covering other areas would be fine things and I hope to add to them myself > > when I am a bit more familiar with Clojure. > > > > That was a bit more rambling than planned. > > > > Happy New Year > > > > Tom > > > > 2008/12/31 Simon Brooke <still...@googlemail.com> > >> > >> On Dec 29, 3:15 am, Rich Hickey <richhic...@gmail.com> wrote: > >> > On Dec 28, 8:13 pm, "Mark Volkmann" <r.mark.volkm...@gmail.com> wrote: > >> > > >> > >> > I'll not argue for making code harder to read, but I have to object to > >> > most of your example. > >> > > >> > Making something 4x longer does not make it easier to read. > >> > > >> > Redundant comments are useless. > >> > >> This is the excuse continually trotted out by people too lazy to > >> comment, or who think themselves superior to merely mortal programmers > >> who have to work in teams and actually communicate with people. > >> Redundancy in communication is almost never redundant; think of it as > >> a checksum. > >> > >> ... > >> > >> 'Redundant comments are useless' is the mantra of the dilettante, the > >> amateur, and the cowboy. > >> > > > > > > > > > > > > > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en -~----------~----~----~----~------~----~------~--~---
