The Computational Limits of Deep Learning - <AUTHOR> https://arxiv.org/abs/2007.05558 <comment><USER3> My interpretation of current ML solutions is that it's mostly brute force statistical models hoping to hit a satisfactory p-value (some implementations being more elegant in the brute force than others). The calculating power defines the limits of the finite domain you can apply the solution towards.

A simplified analogy that I believe is applicable is the application of flocking behavior in birds. Current ML implementations would demand a large dataset of groups of birds in flight, both flocking and non-flocking, and curating the correct p-value of brute-forced models that allege to predict whether behavior is flocking or not (and in the case of an individual bird whether it is appropriate flocking behavior given the individual behaviors of birds in the dataset and their circumstances). But flocking behavior is easily modeled right now, and has been for decades, using simple rules for individuals and depending upon emergent phenomena within a group.

I'm concerned that most of the ML efforts now are merely attaining the low- hanging fruits of brute force but will run into a wall that halts progress at the level of relatively "easy" things solved by worms and other comparable biological solutions since so many domains have a level of complexity that would exceed any realistically imaginable level of simple mathematical computing power.

<comment><USER4> This is one of my favorite quotes, which I think summerizes what you wrote in one sentence:

"artificial intelligence is the second best way to solve any problem"

(KJ Astrom, UC Santa Barbara)

<comment><USER5> eh, I get the point, but not really, at least for modern AI. Data-driven approaches just work better for large classes of hard problems. There's not going to be some simple algorithm to identify a kitten in a photo.

</comment></comment></comment><comment><USER6> We can look Deep Learning's growing demands for computation and despair, or view those growing demands as an economic incentive to develop more powerful hardware that uses energy more efficiently at a lower marginal cost and in a more sustainable manner.

In other words, Deep Learning's growing need for computing power seems to have reached a point at which it is now motivating fundamental research to find greener, cheaper, more energy-efficient hardware.

The economic incentives are _very_ powerful: Whichever companies (or organizations, or countries) find ways to harness the most computing power at the lowest marginal cost will win the race in this market.

\--

PS. The same could be said for Bitcoin mining: it is also motivating fundamental research to develop greener, cheaper, more energy-efficient, more powerful hardware. Whoever finds ways to harness the most computing power at the lowest marginal cost will make the most money processing transactions on the network.

<comment><USER7> Saying that increased demand for compute will spur exponential growth is like saying that increased cross-Atlantic travel will spur the development of supersonic passenger airplanes, which we know is the opposite of what happened.

Alex Krizhevsky's revolution was to find a way to train large neural networks using existing hardware that was optimized for linear algebra. Linear algebra is literally the first applied problem that was studied in computer science, with papers that were written by Turing and von Neumann. It's the most mature field in computing and is long out of steam. Progress since AlexNet came from scaling $$$ not scaling tflops. There will not be exponential growth in compute performance.

<comment><USER8> TPUs and waferscale hardware beg to differ.

<comment><USER9> 1\. TPUs haven't really beaten newer GPUs significantly in performance.

2\. Wafer scale integration and other advanced packaging approaches are qualitatively different types of computing advances that CMOS scaling, which provides better, faster, smaller, cheaper and at the same time, due to Dennard Scaling, reduces power.

</comment></comment></comment></comment><comment><USER10> Reading this paper reminds me how important it is for AI to continue to evolve it's core algorithms.

Deep learning models are effectively pattern matching machines that cannot separate causality from correlation. As we throw more compute and $$$ at deep learning models we will experience diminishing returns in performance because of this.

For us to achieve AGI[0], the holy grail of AI, we will need to develop algorithms that can recognize causality somehow. Judea Pearl's "The Book of Why"[1] does a great job articulating why this is important. Deep learning is a big leap forward and we're only beginning to see its impacts, but it's not sufficient to achieve AI's most ambitious goals.

[0] [https://en.m.wikipedia.org/wiki/Artificial_general_intellige...](https://en.m.wikipedia.org/wiki/Artificial_general_intelligence)

[1] [https://www.amazon.com/Book-Why-Science-Cause- Effect/dp/0465...](https://www.amazon.com/Book-Why-Science-Cause- Effect/dp/046509760X)

<comment><USER11> The limitation here is not necessarily in the algorithms but in the data.

There's no reason to suppose that it's even possible to recognize causality and separate it from correlation purely from static observations - <USER2> others, Judea Pearl has written a bunch about it, this year's ACL best theme paper (Bender&Koller, Climbing towards NLU: On Meaning, Form, and Understanding in the Age of Data) was on a very similar topic, IIRC there's neuroscience research that suggests that mammals can't "learn to see" functionally if they only get visual input that's not caused by their own acts, etc. It's highly likely that _no_ algorithm or mind can learn what you propose solely from the data (and the type of data) that was available to train GPT.

It seems that recognizing causality requires intervention, not just observation, it requires active agents, not just passive specators. It requires "play" and experimentation. Learning language meaning requires at least some grounding and alignment with reality. The problems of causality illustrate the limitations and necessity of integrating models with the environment, they do not indicate any fundamental limitations with model structure itself; perhaps deep learning isn't sufficient for learning these structures, and perhaps it is, as far as I know we don't have any good evidence to justify assuming one way or the other.

On the other hand, if/when some artificial agent has learned the core concepts of causality and language grounding in some small environment - using whatever algorithms are required for that - then it seems plausible that a GPT-like system could be sufficient to provide the mapping to extend these concepts to the whole range of things that we talk about; once the agent _understands_ (according to whatever reasonable nontrivial definition of "understands") the concept of causality for _some_ actions, it can learn the causality of all the other actions which are described if you read all the written text in the world.

<comment><USER12> So goes the old teachers' proverb: "Tell me and I forget, show me and I may remember, involve me and I understand."

</comment></comment></comment><comment><USER13> The current state of the field is reminiscent of discrete mathematical optimization in the late nineties. The computational power was increasing rapidly back then but our our ability to solve problems with more than a hundred of binaries hadn't improve almost at all. It was only after new theoretical results in integer programming found their way into the solution algorithms when we saw a stepwise increase of performance.

<comment><USER14> Interesting. Could you point me to some history article about that?

<comment><USER13> [https://www.math.uni-bielefeld.de/documenta/vol- ismp/25_bixb...](https://www.math.uni-bielefeld.de/documenta/vol- ismp/25_bixby-robert.pdf)

The story narrated by Bixby, the cofounder of CPLEX and Gurobi the two best available commercial mathematical optimization solvers. The magic happened in CPLEX V6.5 back in 1999 with almost 10x y—o-y performance improvement.

</comment></comment></comment><comment><USER15> ,,This article reports on the computational demands of Deep Learning applications in five prominent application areas and shows that progress in all five is strongly reliant on increases in computing power.''

I don't agree with the conclusion of the paper. The computing architectures have been improving dramatically over the last few years, and almost any task that was achievable 5 years ago with deep learning is orders of magnitudes cheaper to train.

The energy resources taken by deep learning is increasing because of the huge ROI for companies, but it will probably slow down as the compute cost gets close to the cost of software engineers (or the profit of a company), because at that point researching improvements to the models gets relatively cheaper again.

</comment><comment><USER16> I wonder how long we can continue overfitting these benchmark datasets as a community of researchers? How much is ImageNet is labeled incorrectly/subotimally?

<comment><USER17> As long as there are PhD students in need of a dissertation.

</comment></comment><comment><USER18> What's disheartening, is that all the charts are in log scale for "Computation (Hardware Burden)". These days it feels like any non-trivial achievement in the field of ML requires resources of the state actors. Maybe that's the sign of ML becoming a mature field like Physics, where collective efforts like CERN and ITER are required, and all low hanging fruits have been picked. Bot it also goes in contrast with how Mathematics and Statistics research has been made before. In these fields a paper usually has only one to three authors, and one man can make a difference. In ML, it's probably not the case anymore.

</comment><comment><USER19> Will it? Or, like capital-intensive industries of the past, will deep learning funnel its profits into bigger and bigger computers, as has been done in the past and will be done again?

<comment><USER20> These are order-of-magnitude increases. If it costs $5m to train GPT-3, which is 100x more compute than GPT-2, then it may cost $500m to train GPT-4, and $50b to train GPT-5. This is what is meant by economically (not to mention environmentally) unsustainable.

<comment><USER19> Environment aside (I don't even think the CURRENT rate of training is environmentally safe) -- I see no inherent problem with a 100x increase in cost per step holding anybody back. Once it's trained, you can run it much cheaper. Who's to say $50 billion of value can't be extracted from GPT-5?

<comment><USER21> Using electricity is not inherently damaging to the environment. Very low cost and high power zero-carbon generation sources exist (hydro and nuclear). For scale also keep in mind that all the datacenters in the world still use much less power than is used for smelting aluminium.

<comment><USER22> Also, processors turn electricity into heat - if you can find a useful way of harnessing that heat, the computation is practically free. Deep learning is fairly latency-insensitive and is almost never mission-critical, so it's not inconceivable to imagine that the boiler rooms of apartment buildings and office blocks could become mini-DCs.

<comment><USER23> Also, once there are billions of value to be extracted, specialized chips will appear just to train those models (e.g. wafer scale analog processors, could easily be 3 orders of magnitude more efficient than GPUs/TPUs).

</comment></comment></comment></comment></comment></comment><comment><USER24> More computation = more data. That's the real problem. Processors will get faster but for some applications we'll never have more data. So yes, new approaches are needed.

</comment><comment><USER25> There's a big difficulty difference between Engineering, and Reverse Engineering.

If you want to build a supersonic fighter, it's a lot easier if you can look at how someone else has done it. This focuses your search to certain parts of the possibility space, saving tons of time. It gives you proof that certain techniques can in fact work. This is why the proof-of-concept, or technology demonstrater, is such an important milestone. It's why countries do so much technology espionage.

Maybe it takes us a of computation to get the first NN that achieves a given performance level on a task we care about.

But then we have an artefact we can reverse engineer. At a minimum, we can compress it, sure. But ultimately we can do science on it to find out how it's doing what it's doing, to look for the learned architectures within.

It's going to be a lot easier to do this on a deep learning system, than a biological one.

Maybe we wouldn't do this while it's cheap to just scale compute, but eventually we will. And the new understanding we get will probably enable us to build new generations that are even more efficient.

This is really just a gut take, but it's an argument for optimistism here.

</comment><comment><USER26> a complementary reading piece should be sutton's "the bitter lesson", which more or less argues that ai methods/techniques that "leverage computation are ultimately the most effective, and by a large margin."

[0] [http://www.incompleteideas.net/IncIdeas/BitterLesson.html](http://www.incompleteideas.net/IncIdeas/BitterLesson.html)

</comment><comment><USER27> That also means only few monopolistic behemoths can do state of the art AI. Good luck for an independent researcher to pull GPT-3.

<comment><USER28> What does OpenAI have a monopoly in, exactly?

<comment><USER27> Currently, a monopoly on text generation. And they are not "open" anymore, being a commercial venture closely associated with Microsoft.

</comment></comment></comment><comment><USER29> Time to ask Deep Learning to accelerate Moore's Law</comment>


Ask HN: Who's building prototypes/ iOS apps for a flat rate? - <AUTHOR>

I've seen a few posts from developers offering to build someone's prototype for a flat rate in the past month or two. Specifically I remember an apparently reputable hacker offer to do so for $5000 with the intention of helping someone with no technical skills create a functional product that can be shown to investors/etc and improved on from there. Are there more of you out there? Right now I have a geolocation iPhone app idea that I'd like to pay to have built. I live in San Francisco and am willing to work with someone from the area. Please reply here or email me if you're interested- Thanks! <comment><USER2> What about out of area?

<comment><AUTHOR> I had a bad experience working with someone out of area (if you check my posting history here, you'll be able to find more information on the issue) and so I would greatly prefer working with someone in the bay area in order to meet in person. However, I suppose someone with great references/other forms of credibility could be considered.

<comment><USER3> I would say bad experience know no boundaries, I have heard horror stories from people who contracted the firm across the hall. It is dependent on the developers, not their location. IF you don't find someone local let me know, I am booked solid right now, but I can refer you to a good developer who could get you into a prototype for that range of investment. My email is in my profile.</comment></comment></comment>


Golang and Rust = Vlang - <AUTHOR> https://github.com/vlang/v <comment><USER2> New languages are something sorely needed.

However, has Vlang delivered on its promises? There were several heated discussions around that topic in HN.

<comment><USER3> It seems to be doing much better, has attracted lots of contributors, and is no more mere vaporware but an actual language on GitHub, so there's that...

<comment><USER4> For me the problem is that the item in the section:

> _Key Features of V_

> _Fast compilation: ≈100k — 1.2 million loc /s_

> _Performance: within 3% of C_

look like facts, but last time I checked it was only a whish list, or some desired properties. They are not backed by benchmarks.

<comment><USER5> Things are moving so fast you've gotta dig into the Discord chat history to see info here. But yeah, it's achieving its goals.

</comment></comment></comment></comment><comment><USER6> V looks really promising like something between Go and Rust. but there is still so much work to do, ecosystem are not cheap in terms of resources and community. nice looking "another one" language may be not enough to get succeed

</comment><comment><USER7> What's up with the editorialized submission title?

Did we ever figure out what V's author is trying to sell? The closest I came to a motivation is that they want attention, acclaim, and a cult of personality; y'know, the Wolfram special.

<comment><USER8> Attention and acclaim (and respect and admiration) are perfectly fine motivators. "Cult of personality" seems "editorialized".

<comment><USER7> But I didn't put "cult of personality" in the title. I'm talking about [0], specifically:

> [P]lease use the original title, unless it is misleading or linkbait; don't > editorialize.

My question is really for the submitter, although it doesn't look like they're going to come back and explain themselves. V isn't somehow a sum of Go and Rust. Seriously, _look_ at that stupid stupid statement. Consider it in its fullness. Imagine how many small misconceptions about the nature of programming must have been added together in order to get such a pseudoprofound utterance.

Cults of personality are a real problem when it comes to programming languages. By my quick estimates, about half of TIOBE's list of popular programming languages are languages that exist due to a mythologized Great Man (Ruby, Python, C++, PHP, JavaScript) or small conclave of Great Men (C, Go, Swift, Java) having deep insights or understanding of programming. However, there's no serious evidence from outside our system to suggest that any programming language is good, and that should put the entire premise into doubt.

[0] [https://news.ycombinator.com/newsguidelines.html](https://news.ycombinator.com/newsguidelines.html)

<comment><USER3> > _[P]lease use the original title, unless it is misleading or linkbait; don > 't editorialize._

Of thousands of readers on HN, and thousands of people who submit stuff, I'd say a small minority has read or cares to read the submission guidelines. I'm on HN for over 10 years and hardly ever read them, much less having internalized them (not the poster, just saying).

So the "don't editorialize" rule is not that known to everybody as you assume, as to make "self-evident" that someone purposefully violated it. It's more probable that they just posted with a title they liked and didn't know they need to copy over the original one...

</comment></comment></comment></comment><comment><USER9> does V do GC like golang or no GC like rust?

<comment><USER9> oh "There's no garbage collection or reference counting. V cleans everything up during compilation. If your V program compiles, it's guaranteed that it's going to be leak free." but "Unfortunately, this only currently works for basic situations; manual management is required for more complex cases, which are another WIP."

<comment><USER10> That makes the title of this post more like a "worst of both worlds". Not good marketing.

I read about this or a similar approach before. I've got no idea how they think they'll pull it off without requiring rust like annotations or reducing expressive power to something below TM equivalence. Or "leak free" doesn't mean what I think it does.

<comment><USER5> Alex is about to release the autofree functionality: [https://discordapp.com/channels/592103645835821068/592842126...](https://discordapp.com/channels/592103645835821068/592842126304477184/659967233195376661)

Notice that after it's stable it will be on by default with a `-noautofree` option.</comment></comment></comment></comment>


Better Worlds: Skin City - <AUTHOR> https://www.theverge.com/2019/2/6/18197632/kelly-robson-sci-fi-story-privacy-ar-skins-better-worlds <comment><AUTHOR> I'm not sure how this is supposed to represent a "better world". Personally this seems like a dystopian nightmare.</comment>


I've never seen a language's style guide recommend avoiding comments before - <AUTHOR> http://www.haskell.org/haskellwiki/Commenting <comment><USER2> Avoiding comments that do what your code should be doing is common practice, and I think that's what this style guide is recommending.

Comments are useful to describe __why__ you're doing something, often when you are not able to change the unexpected behaviour. Whenever I build an API library, my code is littered with comments like "Acme Corp API requires this happens before that" with a link to that bit of the API documentation.

Here's a C++ example about "documenting surpises" (taken from Steve McConnell's Code Complete:

        for ( element = 0; element < elementCount; element++ ) {
            // Use right shift to divide by two. Substituting the
            // right-shift operation cuts the loop time by 75%.
            elementList[ element ] = elementList[ element ] >> 1;
        }

And a Java example:

        /* The following code is necessary to work around an error in
           WriteData() that appears only when the third parameter
           equals 500. '500' has been replaced with a named constant
           for clarity. */

        if ( blockSize == WRITEDATA_BROKEN_SIZE ) {
             blockSize = WRITEDATA_WORKAROUND_SIZE;
        }
        WriteData ( file, data, blockSize );

He also gives a whole list of situations in which comments are a bad idea, and it's similar to the OP.

<comment><USER3> Completely agree :) In some cases I prefer to wrap it in an aptly named function, but in other cases I prefer the whole algorithm to be in a single function, making comments a very useful tool for "naming".

<comment><USER4> _in other cases I prefer the whole algorithm to be in a single function_

A modern compiler can inline most of your function calls if you like. That way you can factor the code appropriately for both concerns.

<comment><USER5> Putting the whole algorithm in a single function isn't for the compiler's benefit but for the reader's. Especially in languages with side effects any function call you need to analyse takes time and then you need to come back to the main function and remember your mental state.

Please note that in many cases putting an algorithm in a single function is the wrong choice but there is also a cost in splitting it.

</comment></comment></comment></comment><comment><USER6> Of course everyone thinks they always write good clean code and therefore don't need comments to elaborate on what the heck is going on.

Unfortunately, having been doing this trade for 30+ years, I've found most people write crappy code in a hurry to try to hit some deadline based on incomplete requirements and confusing business rules. A few precious comments stuck in there can help the next guy, months or years later, figure out what the heck your original intent was or why a block of code exists at all.

As I get older, I find it helps me remember what I was doing.

One of my software developer friends was fond of saying: "the worst code I ever saw was my own!"

YES if your code is clean and elegant and well named and clear you don't need to explain anything in common language.

YES you should strive for such.

However, the REALITY is your code sucks and no one is going to want to have to figure out what the heck you were doing. A few comments would really help.

The next reality is that the typical developer may be literate in a dozen or more languages and the language du jour that you coded so elegantly in has fallen out of favor and no one remembers those dusty corners you so beautifully exploited to make something work.

Comments would help even more if you learn to use some basic grammar and spelling when you create your comments. (It doesn't have to be literature, but try to make your comments as readable as you think your code is - please!) Nothing will turn another developer off to trying to decipher your code than a few comments that make you look like a moron.

Style guides that eschew comments, IMO, are counterproductive. They feed on the developer's ego and disregard reality.

Comments cost essentially nothing to add to your code and can save it from an early death and complete refactoring by the next guy who comes along.

<comment><USER3> I wonder where the idea comes from that people that write code that's hard to understand, will write comments that are easy to understand.

<comment><USER7> Good programmers sometimes have to do weird things.

Leaving a note about that weird thing is probably a good idea.

<comment><USER8> In my experience:

A novice programmer will just do the weird thing (no comments).

An intermediate programmer will spend twice as much time as they should, trying to think of an elegant solution, before doing the weird thing anyways (and maybe leaving a comment).

A good programmer will just do the weird thing, leave a comment, and move on.

<comment><USER9> I somewhat agree, except possibly for the "should". I think that trying to think of an elegant solution (and then accepting that you can't, where appropriate) is an important learning process. Of course this depends on context; spending time on learning is sometimes inappropriate.

<comment><USER8> I agree with that. Perhaps more accurate phrasing would be "more time than the seasoned developer would have". Part of getting to the third stage is learning those types of lessons during the second stage - which only comes with experience.

</comment></comment></comment></comment></comment></comment><comment><USER10> Robert C. Martin's Clean Code book has a great section on comments:

\- The proper use of comments is to compensate for our failure to express ourself in code. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. So when you find yourself in a position where you need to write a comment, think it through and see whether there isn't some way to turn the tables and express yourself in code.

\- The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong. The reason is simple. Programmers can't realistically maintain them.

\- Comments Do Not Make Up for Bad Code! One of the more common motivations for writing comments is bad code. We write a module and we know it is confusing and disorganized. We know it's a mess. So we say to ourselves, "Ooh, I'd better comment that!" No! You'd better clean it! Clear and expressive code with few comments is far superior to cluttered and complex code with lots of comments. Rather than spend your time writing the comments that explain the mess you've made, spend it cleaning that mess.

``` // Bad:

        // Check to see if the employee is eligible for full benefits
            if ((employee.flags & HOURLY_FLAG) &&
            (employee.age > 65))

        // Good:
        if (employee.isEligibleForFullBenefits())

```

<comment><USER8> Sometimes, comments are a justification. Sometimes you have to do things that seem like the wrong thing to when reading the code (like sending a POST request instead of a GET when a GET is clearly more appropriate, but you have to talk to a poorly-written API that will only respond to POSTs on that route). Comments help rationalize that decision for the next guy.

I also find TODO comments quite helpful. It requires far fewer brain cycles to process a TODO comment than to parse the code, figure out what it's doing, and make an assertion that it's incomplete.

Comments can also make code much more approachable to junior programmers, who may not have heard of principles like Tell Don't Ask, or Composition Over Inheritance. When I'm working with a junior dev, I find that comments usually reduce the number of interruptions I receive that are along the lines of, "Hey why did you do this thing this way?"

Really, it's just not a good idea to make sweeping generalizations like, "Comments are always failures". The real world has time and budget constraints, and comments are sometimes the most effective way to satisfy those without screwing the next developer to read the code.

<comment><USER9> If you're systematic about the syntax of your TODO comments, you can also 1) jump to them, 2) traverse them in order of priority, 3) automatically surface changes to the list of TODOs as comments in commit messages, and 4) use commit hooks to refuse to commit code with overly severe TODOs to certain branches.

<comment><USER8> I do 1) pretty frequently, and while I don't go so far as 4), I do use total TODO count as a heuristic from time to time.

<comment><USER9> Yeah, I've never got as far as 4. I do 1-3 on my main project at my day job.

</comment></comment></comment></comment></comment><comment><USER11> I see rubbish like this in PHP (and Java) code all the time:

        /**
         * Frobnicates a foobar
         *
         * @param Foobar $foobar The foobar to be frobnicated
         * @param int $intensity The intensity with which the foobar will
         *    be frobnicated (defaults to 4)
         * @return mixed The result of frobnicating a foobar
         */
        function foobar_frobnicate(Foobar $foobar, $intensity=5)
        {
            // frobnicates the foobar
            return $foobar->frobnicate($intensity);
        }

It's utterly ridiculous.

Pretty sure I've been guilty of this in the past, too. As I recall, the documentor tools make a lot of noise if you don't supply wasteful and irrelevant values for every single little thing even if it's blindingly obvious from the symbol, context or idiom what it means and what it does.

<comment><USER12> I think we can all agree that this is the most blatant example of useless documentation.

<comment><USER13> It's a bit contrived but it's not even as useless as it would appear to be (if you forget about the likely intentional mismatch between the default value and its documented value).

The purpose of this comment is obviously not to clarify the code for someone working on it, but to ensure the automatically generated API docs stay consistent. I write comments like these above functions all the time, because we have a zero-warning policy for doxygen comments over here, to prevent people forgetting to document public API methods (or slacking off out of laziness). Sure, the comment block is redundant since it contains nothing that cannot be derived from the parameter names and the name of the function, but it does make sure a doxygen run will not spew warnings and errors all over the place, drowning out uncommented methods with far less obvious functionality or parameters. The redundancy is a small price to pay to enforce a good self- documented API.

I really don't understand any of the discussions about not documenting code because it should be 'clean and obvious'. First of all that's mixing up 'how' and 'why' code is like it is, second it's a small effort to write and maintain code comments (contrary to what some people like to suggest otherwise), third it can help you organize your thoughts while you are writing the code (write the steps of your algorithm in comments, then translate them to code), etc.

Personally I also like how the syntax highlighting breaks up blocks of code with API doc comments, which makes it much easier to see where functions start and end when scrolling fast, or how they can separate distinct steps of an algorithm. 'No comments' really is the inverse of 'literate programming', like most of the time, the truth is probably somewhere in the middle.

</comment></comment></comment><comment><USER14> Hmm. This is just one guy's style guide on the public wiki.

[http://www.haskell.org/haskellwiki/index.php?title=Commentin...](http://www.haskell.org/haskellwiki/index.php?title=Commenting&action=history)

It isn't official in any sense.

<comment><USER15> Right, also, it doesn't actually say avoid comments, it just gives examples of where it's best to try and find an alternative.

In the bitcoinj code style guide there is a big section on comments that gives positive examples as well as negative examples:

[http://bitcoinj.github.io/coding- conventions](http://bitcoinj.github.io/coding-conventions)

</comment></comment><comment><USER16> I've always treated comments as code smells. Not necessarily something bad, but something that at least suggests the possibility of suboptimal code.

One of the best cases for comments IMO is documenting an unexpected behaviour on the part of a third-party API. But even then, correct exception / error- handling code can obviate the need for comments in many cases.

If I'm reading code (from an experienced programmer) and I see a comment, I immediately pay attention, because Here Be Dragons.

<comment><USER17> The situation must be differentiated by language/environment. The suggestions for Haskell are certainly not bad. They hold, too, for many systems programming.

For scientific coding, comments should align with the underlying theory for the code: "This implements matrix transposition with regard to ... as defined by ...", so that next generations can align code with papers better.

And when you're in a wacky environment like the PHP runtime or coding for a moving target like the browser, comments might be indispensable to explain one or the other really strange way of doing things, where you simply have no other choice. Look at the [jQuery source code]([https://github.com/jquery/jquery/tree/master/src](https://github.com/jquery/jquery/tree/master/src)), where they comment excessively, which browser quirk they address with which work-around.

<comment><USER18> > For scientific coding, comments should align with the underlying theory for > the code

100x this. Scientific software should be held to a different set of standards than non-scientific software, primarily because you can probably not assume that your reading is familiar with the underlying domain.

<comment><USER19> > Scientific software should be held to a different set of standards than non- > scientific software, primarily because you can probably not assume that your > reading is familiar with the underlying domain.

As someone who works as a programmer and system analyst dealing with code in a non-scientific business domain where I've also worked on the domain side, I don't think that this separates scientific code from any other codes. Programmers often disdain domain knowledge beyond that which they already have found to be immediately relevant. Which is perfectly understandable -- there's a reason they chose to specialize in programming rather than as domain experts in whatever domain.

<comment><USER18> I thought through this some, and your comment resonates -- it's not right to set aside scientific code from other code with a complicated domain.

But I think complicated program segments related to business practices etc. also deserves comments, even just "see spec xyz" or "see section 1.2.3 of code xyz" (similar to how you might say "See Smith et al. '14" in a scientific setting)

</comment></comment></comment></comment></comment><comment><USER20> Comments say _what_ your code does, your code says _how_ you do it. The swap example is trivial, but for most functions it is good to add an API comment, because how you use the function shouldn't depend on how it's implemented, but what it should do, described in the comment. That way you can change your implementation as long as you don't change the contract. In other words, changing how your code does something shouldn't therefore change what it does. And this last part is specified in the comment.

<comment><USER21> Well, this is Haskell we're talking about. Between the name, type signature and the fact that most functions are pure (so, no side-effects to describe), it's often obvious what they do.

<comment><USER22> Like

      (<+>) :: Monoid m => m -> m -> m
      (^?) :: s -> Getting (First a) s a -> Maybe a

As a Haskell beginner I didn't find it to be a particularly self-documenting language. Between the use of custom operators and point-free style you can write a lot of code without naming anything to give a hint about what you're doing.

<comment><USER23> So as another Haskell beginner, let me take a stab at the first one.

      * Return the first parameter
      * Return the second parameter
      * Perform param1 `mappend` param2
      * Perform param1 `mappend` param2
      * Return the mempty value for the Monoid m

The first two are unlikely to be correct, since if all they were doing was returning a particular parameter, then there is no reason to have the Monoid type constraint. The last one similarly makes no sense, since it's a function that is identical to `mempty` irrespective of it's parameters.

The order of operations however should be documented. I'm almost certain that the implementation is the third function, but a one line comment stating that could _possibly_ be useful.

All of my above reasoning was predicated on an understanding of Monoids. So while I'm not sure the right thing to document is the function, I do think an explanation of `Monoids` should be documented in `Data.Monoid`.

PS - Where is that first function defined? I've used a similar operator defined in XMonad, but if I remember right that was defined over Arrows. Also is that second function from Data.Lens?

<comment><USER9> I assume line 4 was meant to be:

        * Perform param2 `mappend` param1

I'd be a little surprised if it was the third option, simply because that's already spelled <>. Hoogle doesn't turn up a definition with that signature, though.

</comment></comment></comment></comment></comment><comment><USER24> Here's a small function from a real world module used in a Haskell web backend. It decides whether a "work unit" is appropriate to pick from a queue. The first iteration was a pretty complex piece of code. When I refactor, I often think "this is unclear and should be commented," but I've learned instead to think "this is unclear and should be factored out and given a significant name." So I ended up with this:

        shouldPickWorkUnit :: (ImportId, WorkUnit) -> STM Bool
        shouldPickWorkUnit (k, u) =
          case hostNameFor url of
            Nothing       -> return True -- Invalid URLs are fast to process.
            Just hostName ->
              takeWorkThat'sAlreadyDone <*>
                (don'tTakeSomeoneElse'sWork <*>
                  don'tExceedTheRateLimitFor hostName)

This way, the domain logic is legible from the actual code, which strikes me as almost always better than having tricky code with comments. Trying for this also encourages "domain-driven abstraction," and this is one of Haskell's greatest strengths.

In fact, the remaining comment can be factored away too:

        shouldPickWorkUnit :: (ImportId, WorkUnit) -> STM Bool
        shouldPickWorkUnit (k, u) =
          takeWorkWithInvalidUrl <*>
            (takeWorkThat'sAlreadyDone <*>
              (don'tTakeSomeoneElse'sWork <*>
                don'tExceedTheRateLimitFor hostName))

Advice like "avoid comments" needs to be taken as a calling for actually spending time and effort to write obvious code, and for using appropriate abstractions!

</comment><comment><USER25> It's doesn't recommend avoiding comments - it encourages to write understandable code and avoid meaningless comments. It is a basic rule of the clean code.

</comment><comment><USER12> The thing with comments is: You should add them for people that don't want to read your code line by line.

I don't want to run my internal compiler in my head when i'm reading your code, so you better make sure there's at least a docblock above every function that describes in 2 sentences what it does so I can get a global overview of what the heck this file is doing.

People that suggest that 'the code is the documentation' are always forgetting that reading code is way more taxing on the brain than reading english.

<comment><USER26> That is exactly why once should take the time to give meaningful names to their functions, classes, and methods. If you are having a difficult time doing it, your piece of code is probably doing too much. Split it into pieces that are more easy to name.

<comment><USER12> I already assume you are using meaningful names for functions, classes and methods, as any self-respecting programmer will do.

I can completely live with a 50 line function that does _magic_ in a legacy project, as long as I don't have to read through it.

'split it into pieces' is everybody's favorite argument, but nobody is going to pay you to refactor it. DOCUMENT IT.

</comment></comment></comment><comment><USER27> I've found there are several topics that even qualified, experienced, reasonable developers will always disagree on. dynamic vs static typing, YNGNI vs future proofing, IDE vs no IDE etc. Usually, a given developers opinion on these topics is informed by their specific experience and what has bitten them in the past.

Code comments definitely fall into this category. I've worked with developers who I greatly respect who are obsessive about code comments. I've even been told that the comments are more important than the code and in that specific context it made sense.

But my own experience and biases make me think code comments are a problem. I like to refer to them as future lies. There is virtually no back pressure on comments to keep them in sync with the code. There is no automated way to verify them and refactoring tools on comments are rudimentary at best. To put it simply, I no longer trust comments and will usually ignore them in order to verify the code itself. I can't count the number of times I've found comments that directly contradicted the code it was commenting. It isn't even uncommon to find comments that are incorrect when they are written!

As to the folks recommending comments that document the "why" of a piece of code, I'd counter that if you have a "why" you have a specification. If you have a specification it should be verified in a systematic way. So performance improvements, or specific client requirements should be encoded in tests so that they don't regress. Comments do not provide that safety.

That's not to say I never comment my code. Just that it always feels like a failure when I do. It is usually because it is cheaper to comment than to provide cleaner code or better verified specifications.

</comment><comment><USER28> It seems like no one here shares my opinion on this: I really like comments, even if they just restate, in English, what the code does. I don't think that's pointless. There is big value in it. I can scan and mentally process English sentences much faster than code. With a heavily commented file you can just skim through the comments until you locate the part you need to work on (then slow down and read the code around it and edit it).

Look at the Backbone.js annotated source [1] (the stuff on the left is just the comments pulled out from the original source JS). The comments make it much, much quicker to grasp what's going on, even though many of them just state exactly what the corresponding code does, which according to the Haskell docs' advice is pointless and to be avoided.

[1] [http://backbonejs.org/docs/backbone.html](http://backbonejs.org/docs/backbone.html)

</comment><comment><USER29> > I repeat: Try hard - very hard - preferably repeatedly - to remove > unexpected behaviour from your program. Comments can never fix unexpected > behaviour.

This is golden!

</comment><comment><USER30> I've seen this many times:

        ...thus they (comments) tend to diverge from actual implementation.

It happens, you update/refactor code, and forget to update the comments. Thus the comments are outdated or worse not applicable anymore. Common mistake by less-detailed oriented developers. Begs the question, in this case is is better to have confusing/incorrect comments, or no comments at all?

<comment><USER31> No comments are better than bad comments. There is nothing worse than a misleading description.

<comment><USER32> I've always gone with the adage: if the comment and code do not agree, don't assume that either of them are correct.

A bad description isn't just a problem in itself, it can indicate a worse problem sat waiting to jump out and bite as you walk by.

<comment><USER33> comments might diverge from behaviour but the code, almost by definition (modulo some crazy magic happening/broken interpreter ) _is_ the behaviour.

<comment><USER31> The best commenting system is a debugger stepping through the code. Unfortunately, I've yet to see a commenting style that is able to really document mental models about how the code works.

<comment><USER34> SEURAT is a research project that attempted this. I was a test subject for it a while back and found it pretty interesting. But its implementation at the time was an Eclipse plugin that probably hasn't been kept up todate. You can find a paper on it on the ACM digital library:

[http://dl.acm.org/citation.cfm?id=1368215](http://dl.acm.org/citation.cfm?id=1368215)

I'm sure the dissertation is available somewhere on cs.wpi.edu, too.

</comment></comment></comment></comment></comment></comment><comment><USER35> I'm a big believer in function level comments in code, in a sort of doxygen- ish style (I write mostly C).

It allows you to document the intended inputs and outputs of the function and state its purpose. This increases maintainability and reusability.

Functions themselves should be short and written as a sequence of logical steps.

I'm also a big fan of doing things right rather than just hacking until it works, which seems to put me in a minority.

<comment><USER21> But the thing is, in C a geocoding function would probably receive two ints and return a string, while in Haskell you'd probably have a function of type "Location -> Address". The type system obviates much of the need for those comments.

<comment><USER35> Indeed, a solid type system would remove some of that need, in C it can be _very_ important to document what _precisely_ that pointer is pointing to. Is it a provided buffer, something allocated and returned? Multiple or single element? etc etc.

I'm guessing Haskell doesn't need that? A simple statement of purpose would still help though?

</comment></comment></comment><comment><USER36> Comments are lousy for describing _what_ you are doing, but there are no alternative to comments for describing _why_ something is done.

</comment><comment><USER37> Similar thoughts were seen in the SICP book.

"In this book we don't use many comments; we try to make our programs self- documenting by using descriptive names."

[http://mitpress.mit.edu/sicp/full-text/book/book- Z-H-15.html...](http://mitpress.mit.edu/sicp/full-text/book/book- Z-H-15.html#footnote_Temp_197)

<comment><USER38> From the era when two poles were Lisp and C, I can sort of see that. In part because of the preference for longer identifier names in Lisp, versus cryptic abbreviations in C, _some_ kinds of comments prevalent in C aren't as necessarily in Lisp. Instead of atoi() you'd have something like _convert- ascii-to-integer_.

In modern Lisp, though, it's still considered good form to include both a docstring, and internal comments explaining anything particularly tricky.

</comment></comment><comment><USER39> Note that this isn't the "official" Haskell style guide. We don't have one (although we probably shouldn't). This is one of the competing guides out there.

</comment><comment><USER40> I'd say the language design and language ecosystem has a LOT to do with it as well. Here are a few lines of Java that I just had to write about 10 minutes ago.

      PendingResult<MessageApi.SendMessageResult> pending = Wearable.MessageApi.sendMessage(mGoogleApiClient, mWearableNode.getId(), path, data);
      pending.setResultCallback(new ResultCallback<MessageApi.SendMessageResult>() {
          @Override
          public void onResult(MessageApi.SendMessageResult result) {
              ....
          }
      }

Okay, now suppose this were a Python-based API instead? Perhaps it could be something like this, after some relevant initialisation:

      wearable.sendmessage(mywearable, path, data)

      @wearable.onresult
      def onresult(result):
        ...

Tell me which one is more in need of commenting.

</comment><comment><USER41> I totally agree with this. I like to put a bigger comment block at the top of my source files explaining the overall concepts and data structures used and then put few actual comments in the code. Instead I think about my variables and function names and make them talk for them-self. Commenting each and every element of your code will just make people (possibly yourself) curse at you when debugging your code and realizing that the comment was rendered obsolete 15 iterations prior and the code does something entirely different.

<comment><USER42> I generally sympathise with your sentiment - I think this jives fairly well with comments talking about 'why' rather that 'what'. I do favour function- level comments quite a bit for more complex functions.

That said, I think some of the commenters in this thread should spend time maintaining a MLOC+ sized code base before dismissing comments as 'code smell'. Even in well-written code, if you're a maintenance programmer who is unfamiliar with a particular functional area, a few comments talking about the overall purpose of the code and why it works the way it does can save you enormous amounts of time.

Finally, if people are letting comments go out of date, IMO they have a quality issue. Either the comments are useless and should be removed, or they're useful and should be kept up to date. If your developers are letting useful comment areas go out of date, it should get caught by code review.

</comment></comment><comment><USER43> Leo Brodie says in "Thinking Forth" in the style section: "The most-accurate, least-expensive documentation is self-documenting code". I am sure there are other prior examples.

</comment><comment><USER44> I agree. Comments sometimes make it difficult to go through the source code. That's why I always loved Java naming convention that suggests variables and method names to be self-explanatory.

</comment><comment><USER45> I currently write docblocks for everything I code.

It's crazy how much time I spend on them and sometimes they are confusing because the specs change and I keep forgetting to add/remove/update something in a docblock when I rewrite some part of the code it documents (I'd say between 10-20% of my commits are docblock updates).

I believe brief or even no documentation may be the best approach until you are on the verge of releasing a stable version.

While you are on developing and testing mode, it seems a better idea to forget about comments and focus on modularity.

After all, Why would I need comments if all the rest of my team sees is an interface satisfying a previously established and well defined contract? That's why docblocks should be only documenting public interfaces, some kind of dump taken from the part(s) of the contract they implement.

I'd consider instead other top priorites on those phases:

\- Keeping an homogeneous codebase in regard of design and coding guidelines and conventions.

\- Re-factoring before it becomes a problem

\- Writing neat unit and integration tests

And, the most important:

\- Keeping a channel open with the client, constantly feeding guided demos and prototypes showing your progress to make sure you are on the right track and you didn't get it backwards, updating specs and being realistic about what can be done and what not in which time frames with the provided resources.

</comment><comment><USER46> > I've never seen a language's style guide recommend avoiding comments before

An official style guide? Maybe. But it is one of common philosophies. See for example:

"If you need to comment something to make it understandable it should probably be rewritten."

[http://kotaku.com/5975610/the-exceptional-beauty-of- doom-3s-...](http://kotaku.com/5975610/the-exceptional-beauty-of- doom-3s-source-code)

</comment><comment><USER47> The stablished policy is: "don't use comments to replace proper names and abstractions".

I wrote more about this here (it's Lua code, but it applies to any language):

[http://kiki.to/blog/2012/03/16/small-functions-are-good- for-...](http://kiki.to/blog/2012/03/16/small-functions-are-good-for-the- universe/)

</comment><comment><USER48> This is not convincing to me because the examples are trivial:

        -- swap the elements of a pair
        swap :: (a,b) -> (b,a)

Yes this is redundant.

        let b=a+1   -- add one to 'a'

Yes this is also redundant

Does it mean that every piece of code can be expressed as clearly as in a one- line comment in natural language? I don't think so.

<comment><USER49> The argument is not to never use comments, but rather to avoid bad comments.

<comment><USER48> I realize this, but the article doesn't provide any clear definition of what actually is a bad comment. It only gives trivial examples of bad comments such as "increment a by one".

Since I don't think anyone here would argue that "increment a by one" is a useful comment, the part about duplicate/obvious comments isn't adding much to the discussion about the usefulness of comments.

Nevertheless, it's true that comments cannot be checked by the compiler, and that's a more interesting point, I think.

</comment></comment></comment><comment><USER50> The article correctly advices against commenting the obvious. I think it is often practice by novice programmers to assure themselves about what the language expression actually does.

What the article omits is the suggestion of commenting the right way, i.e. adding reasoning or the description of the high level logic behind the code.

<comment><USER51> Yes, obviously the examples given in the link are bad style of comments. But sometimes you need to explain the reasons behind the (Haskell) equations, just like one would do in a Math paper. So there's a use case for the literate Haskell files *.lhs ([http://www.haskell.org/haskellwiki/Literate_programming](http://www.haskell.org/haskellwiki/Literate_programming)).

</comment></comment><comment><USER52> Code may explain _what_ your code is doing, not necessarily _why_ it is doing what it does in the way it does.

Comments may be a code smell when it is necessary to explain what your code is doing.

Anywhere where you have some freedom to solve a problem one way or the other it may clarify why the implemented approach was chosen.

</comment><comment><USER53> Comment only magical code, but don't write magical code.

</comment><comment><USER54> There are times when you absolutely want to comment something like an "Add" or "Swap" function.

eg.

// The reason we use a custom swap function instead of

// the one that is shipped with the framework is because

// of an edge-case that occurs quite frequently in our

// scenario

// Refer to Change Request 345.

void Swap (Foo a, Foo b) ....

<comment><USER55> I think you are missing the point there. Sure, I completely agree with you that those comments are crucial, but they are not informing about the code doing a swap, they are explaining the need of the applied workaround.

<comment><USER8> That's precisely the point. In most cases, _what_ your code is doing should be obvious; the _why_ , as others have stated, would be otherwise completely out- of-band information, which explains the necessity for comments.

</comment></comment></comment><comment><USER56> Comments I liked to write were when I found successive optimizations (lots of symmetries in the algorithm) leading to very short code. Almost too factored to be understood easily so I added a comment wall above telling the steps I went through before hitting the final code below.

</comment><comment><USER57> It is easy to spot (most of) the experienced coders from the newbie coders. Any programmer who has written his salt worth of code knows that comments can save your ass. Come back to some code ten years later and you can sit there staring at a bit of code no bigger than your thumb wondering what the hell it does and often it doesn't become clear until you shove some test samples down its interface and see the result. Whereas a simple comment is all it would have taken to clear it up from the start. People who argue that comments can get out of whack with code, well, of course they can, but that's no excuse. That's just a failure on the programmers part to always update comments when the code changes.

</comment><comment><USER58> Personally I have no problems with comments in code for complex functions etc. But pointless comments like this below drives me insane.

// get the user $user = $this->getUser();

Times that by the thousands of lines in a project and you have one big headache!

<comment><USER47> > Personally I have no problems with comments in code for complex functions > etc

I hope you have a problem with complex functions. (They should be made as simple as possible).

<comment><USER31> Why fear complexity when its the only way to get something done, other than not doing it?

<comment><USER25> There is no such complex function that can't be decomposed to bunch of simple(r) functions.

<comment><USER31> Often only with a deep understanding of the complex problem to understand its simplicity. But you have to ship in 4 weeks, so why not just get something working first?

<comment><USER25> > But you have to ship in 4 weeks, so why not just get something working > first?

Of course, this sometimes happens, but it shouldn't be encouraged. This way you are creating technical debt, which will be very expensive to pay off.

<comment><USER31> I actually work on problems that haven't been solved previously (or why not just get a dev to do it rather than a researcher). I get offended when some dev who writes web apps connecting to databases all the time says "all code should be simple." They really don't have a clue.

</comment></comment></comment></comment></comment></comment></comment><comment><USER59> It's often a good idea to comment "why" the code exist, if it is non-obvious (e.g. it's obvious to sanitize input parameters). The comment must be short and possibly point to a ticket wrote somewhere else.

It may be a good idea to comment "what" the code does, if it isn't clear (the code itself is "how" it is done, but "what" does it do may be hard to read, e.g. sometimes you use a clever hack for performance reasons).

As always, handle with care :-)

</comment><comment><USER60> I was always told that if someone couldn't tell what your code was doing by glancing at it, you'd done it wrong and should re-write it.

I know that's absurd in practice, we don't always have the time but I've always used comments as a last resort.

If I need to comment code to make it understandable at a glance, so be it but I'd rather avoid them all together and rewrite until it's clear enough without them.

<comment><USER61> I disagree with that sentiment.

Using Python or Perl it is easy to go from a for loop to a map or list comprehension. For many less experienced programmers it will make it less readable and more difficult to comprehend. Using a more functional approach will usually lead to less side effects and silly bugs, so I prefer to code this way, and add a comment to explain what the line is doing if it is not obvious.

</comment></comment><comment><USER62> Write comments that explain why a certain line is there.

Let's say you are parsing a standard tab delimited file. You find that the tab delimited file has some non-standard features, so you have to write some extra lines of code to handle it. For people who thinks the code just parses a standard tab delimited file, these lines will be confusing, so you comment these lines and say why you included them.

<comment><USER63> Or create a function to handle that case, name it appropriately, and call it. Thus, no comment is required. You can also test the additional method in isolation, if you wish.

I appreciate that this type of thing is language dependent.

</comment></comment><comment><USER64> This style guide is NOT against comments. It is just stating the obvious best practices which have always been around for all languages ...

</comment><comment><USER65> This submission needs to have a different title. It's not very clear whether the submitter is being genuinely surprised or sarcastic.

<comment><USER66> I would say, never assume sarcasm is in play unless it's absolutely clear. So I think this title is fine.

If the OP meant to be sarcastic, that's just like me saying "yes" when I mean "no"\---my mistake, not yours, and you can't be blamed for assuming I meant what I said.

</comment></comment><comment><USER67> This style guide DOES recommend avoiding unnecessary comments and is an easy one to understand and remember. Good start for all novice coders. [https://google-styleguide.googlecode.com/svn/trunk/shell.xml](https://google- styleguide.googlecode.com/svn/trunk/shell.xml)

</comment><comment><USER68> Linkbait title. Rolls eyes yet again.

</comment><comment><USER69> Martin Fowler's _Refactoring_ says that, possibly paraphrasing here, most comments are bugs.

I do favor putting a short comment on some methods/functions/procedures.

</comment><comment><USER70> Articles about writing code without commenting sound like articles about driving your car without using the brakes: theoretically possible, but impractical.

</comment><comment><USER71> Its quite common in coding communities and style guides.

</comment><comment><USER72> Comments aren't necessary at all. If the code was difficult to write, it should be difficult to read. :-P

</comment><comment><USER73> Read the linked page. This one doesn't either. It says to prefer fixing bugs over documenting them.

</comment><comment><USER74> To rephrase - code makes comments understandable?

</comment><comment><USER75> The article is spot on. Comment as last resort.

</comment><comment><USER76> Good code should be self documenting.

<comment><USER77> > Good code should be self documenting.

Good code needs no test either,... wait no ,that's a stupid thing to say,because nobody writes "good code",code isnt good or bad,it either results in the expected behavior or not.

<comment><USER47> Depends on how you define "expected behavior".

If it means "the machine executes it and is able to produce the expected outputs with the right inputs", and nothing else, then you are missing a key concept about code.

You see, code is not written for machines. If that was the only reason, we would all write direct binary. Code is written for _people_. More specifically, _other people_. (Or you, in the future).

If no one (except a machine) is capable of understanding a piece of code, then that code is indeed bad; it has failed its main purpose. The more _understandable by people_ code is, the better it is.

I agree that once compiled/interpreted, these differences don't matter. Until the next bug or feature request arrives. Then it matters quite a lot.

</comment></comment></comment><comment><USER57> You want a good rule: Write More Comments! Comments are documentation and few programs are ever documented enough.

</comment><comment><AUTHOR> how about a language that has no support for comments!?

</comment><comment><USER78> A partial list of problems

Assume someone who can't write clear code can write clear comments. Also search and replace clear with "readable" "literate" "concise" and last but not least, "correct"

Assume a programmer has full authority over all 3rd party, supplier and customer APIs, interdepartmental processes, and all business logic, management selected fad technologies, such that its logically impossible to be unable to always factor out weird confusing stuff resulting in clear code / clear comments. My program is the world and none have dominion over any of the rest of it and any other conception of reality is wrong. (And edited to add I've gotten involved in some weird "EE" stuff and like it or not, the world itself is plain old weird and illogical sometimes and if you don't like that, a computer programmer can't fix it, only a physicist, or maybe a diety. This isn't a big problem in the world of CRUD apps but it does happen)

Assume comments only exist as a inspirational descriptional prose tool. Sometimes I use them as placeholders for something I know belongs there but either I or the business are not ready. Sometimes I use them as a cheatsheet because I'm personally really uncomfortable. Sometimes I use them as an outline more like names on a map to orient myself than a travelogue.

Assume all programmers fit the management ideal of identical replacable cogs. "How could someone work here without knowing by heart how to convert dBmW into volts or the difference between S21 and S12 microwave scattering parameters, so I have no need to comment this, but I've never actually used this corner of matrix math while employed before so I'll make one of those laughable comments that is a simple linear translation just to help me keep my head on straight.

Assume comments go thru the same code review process as code. If a comment in file A tangentially relates to function Q in file B, and you modify function Q, your code review process will probably examine file B and the comments in it, but how do you ensure file A gets modified? This is especially bad with those "because" style comments. (edited to add, at least date your comments?)

Assume no metrics exist WRT comments to be gamed. Your continued employment and possible promotion exist because of a content free meaningless metric number, perhaps lines of comments. Ask a professional to generate a number, you'll get a nice number, but unprofessional work. Ask a professional to do professional work, and you get professional results and who cares what the number is. That requires a high caliber of management, usually unavailable. Even worse a low caliber of management, the kind most likely to demand adherence to meaningless metrics, is also exactly the type least likely to successfully evaluate the professionalism of the code so they don't end up with good code. So you get meaningless metrics resulting in meaningless comments right next to bad code, if you enforce metrics.

Assume there exists a silver bullet for comments, just like this months silver bullet fad for code also fixes all problems.

(edited to add) Assume there's one human language. I worked at a place where outsourcing and H1B took complete control over corporate IT such that code comments and even some internal documents were no longer written in English. This makes comments rather hard to follow when engineering tries to cooperate with IT. So... I'd love to follow your detailed internal process for dynamic DNS for my spectrum analyzer, but you guys don't use English and we don't use your India language, so...

</comment><comment><USER79> I disagree. You don't need to comment simple and _universal_ concepts like this:

        swap :: (a, b) -> (b, a)
        swap (x, y) = (y, x)

or even this:

        map :: (a -> b) -> [a] -> [b]
        map f [] = []
        map f (x:xs) = (f x):(map f xs)

Those functions actually _are_ self-documenting. Trying to explain them further is just going to clutter the page.

On the other hand, at 10,000 lines of code, a lot of that being parochial business logic, I'm going to want high-level documentation of _why_ all this code exists. My emotional impulse is going to be to throw out all this shit code (in the business world, all code is shit) so please _tell me_ why that is a bad idea. (I know it is, and I'm not going to do it, but please tell me _why_ I'm not going to do it.) I'm going to want an entry point. I can't count the number of days of life I've lost just looking for entry-points in gigantic enterprise codeballs. Like, what actually runs?

Actually, 10,000-line single-programs should be rare-- Big Software is almost always a mistake, see here: [http://michaelochurch.wordpress.com/2012/04/13/java-shop- pol...](http://michaelochurch.wordpress.com/2012/04/13/java-shop-politics/--) but that's another rant.

</comment><comment><USER80> There's similar advice in the Ruby Style Guide - [https://github.com/bbatsov/ruby-style-guide#no- comments](https://github.com/bbatsov/ruby-style-guide#no-comments)

Comments often go out-of-sync with the code, so I think it makes a lot of sense to prefer writing comprehensible code instead of trying to explain with comments something totally incomprehensible.

<comment><USER42> It's weird to me how people will slate low quality code, but think it's okay (or inevitable) to let comments go out of date. If your comments aren't useful, delete them. If they are, keep them up to date. It's part of behaving responsibly towards the rest of your team just as much as writing readable code is.</comment></comment>


A Message to Garcia - <AUTHOR> http://www.birdsnest.com/garcia.htm

<comment><AUTHOR> PG's post today reminded me of this, one of my favorite essays.</comment>


All Your Parentheses Are Belong to Us - <AUTHOR> http://smuglispweeny.blogspot.com/2008/02/all-your-parentheses-are-belong-to-us.html

<comment><USER2> Man, I really need to get around to learning Lisp. (Of course I've been telling myself for a few years now.)

Admittedly, as someone who's only ever used C, C++, C# and Java, Lisp seems so alien that I have a hard time understanding how anyone can do any non-trivial work in it. Then I look at all the awesome stuff that's been done in it and how many people are obsessed with it and, well, I definitely need to check it out at SOME point.

<comment><USER3> Just because you mentioned it, check out this primer: <http://mypage.iu.edu/~colallen/lp/lp.html>

Half way through the first chapter (about 11 pages, which is really shorter than a single nytimes article) it says something on the lines with "you have now a turing complete language at your disposal." At that point you can kind of extrapolate the myriad of possibilities available with the paradigm.

<comment><USER2> Thanks! I'll definitely check this out. Looks like a great starting resource.

</comment></comment></comment><comment><USER4> Kenny hinted that he will stop posting to c.l.l. (or at least cut down on his post frequency) now that he is blogging. If that is true, then "Weeny" just became my absolute favorite blog of all time ;-)

<comment><USER5> I took my first few dives into c.l.l recently (see here [http://groups.google.com/group/comp.lang.lisp/browse_thread/...](http://groups.google.com/group/comp.lang.lisp/browse_thread/thread/dc401f785faaa808)) and I noticed a couple people (left unnamed) with a poisonous negativity, and I'd have to say that Ken seemed like a pragmatic realist with a hint of optimism (kind of like me). I don't even think I would have finished reading the threads I looked at without Ken's comments.

<comment><USER4> I was mostly kidding...but not entirely.

I've been a lurker on c.l.l. for years and I've also seen quite a few interesting threads derailed by Kenny's...uh...UNIQUE sense of humor. The megalomania thing wears a bit thin, for example. I know quite a few noobs that have been helped by his pragmatism ("just pick an implementation and stick with it," "Stop bitching and do something"), but just as many that have left or put him in their killfile because of his off-center tangents and his occasional desire to be the new Erik.

You received a warm welcome because you contributed something useful and didn't just come in bitching and moaning. You were also smart enough to figure out something you could contribute with your current skill level instead of just copping out. Like Kenny, I admire that. And I think Kenny is often very helpful and entertaining. Like many /stereotypical/ geeks, though, I think his sense of humor and social skills are sometimes a bit off. IMHO, a blog is a better outlet for his thoughts...I think it will help the signal-to-noise ratio on c.l.l. and you will still get to read his insights if you subscribe to his feed. I've already subscribed.

<comment><USER5> OK, I think I misunderstood your first comment. My positive opinion of Ken was based on a few threads (< 20 probably) I followed before the warm welcome I got on my own thread. Apparently that wasn't enough to see the side of him that you're talking about.

I couldn't tell if you thought having less Ken on c.l.l would make c.l.l better, or if having Ken write his own blog made it easier to find Ken. Apparently it was the first!

</comment></comment></comment></comment><comment><USER6> Is it just me or do grammatically incorrect prominently placed titles annoy others as well? (I think Lisp rocks, of course, so I don't have an issue with the content)

<comment><AUTHOR> The blog post title is a play on the "All Your Base Are Belong to Us" meme: <http://en.wikipedia.org/wiki/All_your_base_are_belong_to_us>

<comment><USER7> The point being that grammatical incorrectness is less annoying if it creates a snowclone.

</comment></comment></comment><comment><USER8> I'm a huge Scheme fan, and I still think Lisp people are overly smug.</comment>


FSF-Approved Hyperbola GNU/Linux Switching Out Linux for Hard Fork of OpenBSD - <AUTHOR> https://www.phoronix.com/scan.php?page=news_item&px=Hyperbola-Linux-To-BSD <comment><USER2> Interesting bit about Rust being included in the Linux Kernel for drivers.</comment>