Hacker News new | past | comments | ask | show | jobs | submit login

Beyond any educational benefit, what do you see as the advantages of programming in this way?

I and most of the programmers I socialise with tend to see comments as a bad smell; they're fine every now and then but if there are more than a few of them, something is wrong.

How do you prevent the comments from becoming lies? By which I mean, how can you ensure that people updates the comments in accordance with changes to the code that occur over time.

Also what impact do you think this approach might have on the way people write the code itself; naming variables and arguments, decomposing functions into smaller units and so on?

    > Beyond any educational benefit, what do you see as the 
    > advantages of programming in this way?
For me (and I'm just getting started here, I've only been playing around with this in earnest in the context of the little blog engine, and there are certainly many different ways of going about it), it makes the process of exploratory coding feel very different. Instead of thinking up a series of classes or functions that might solve the problem, and starting to write them -- I instead start by outlining (literally) what I want the program to do, and then describe the functionality in paragraphs, and then implement those paragraphs.

When the paragraphs have code below them that does what they say they do, the thing works. When I end up coding myself into a corner, I rewrite the paragraph and change the code. It's really a very different process than usual. It's also definitely more work than just doing code and omitting comments -- it takes a bit of elbow grease to prevent the comments from becoming lies ... but it's the same type of work as preventing bits of your codebase from becoming dead code.

For me, it seems to make me organize code into smaller functions grouped together into sections, use less classes, and care more about putting things in the place where you're talking about them, and less about putting similar things together in one block of code. For example, I started to require things close to the paragraph where I first mention them, instead of putting all requires at the top of the file. At least, that's how it feels so far.

I'm glad to know I'm not the only person who works this way. My source files often have a paragraph or two at the top that explains my intentions for that class/module as well as explains the usage of my domain language. I never see this in other people's code though.

I agree with people who say that the code itself should read very clearly, but the fact is that even when writing an article or paper you have to disambiguate your own writing, clarify your usage of terms and present some context up front. Otherwise people can take away a very mistaken impression of your text, and it is certainly no less true for code.

Quite interesting, I do something similar to that on a smaller scale. When I do a class/method, I usually just put comments describing what's going to happen and that makes me thing of cases I might have missed otherwise and then I add the code below each comment.

Will try literate coffeescript next time I use it.

Comments should not describe what the code does. That should be obvious from the code itself. They should describe why the code does what it does. Hidden assumptions, dependencies or that sort of thing. Things that are not obvious from looking at one particular block of code.

Often comments are transformed into API documentation (JavaDoc, rdoc, tomdoc, docco etc). The less you can put into the type system (or if you use a language with no type system at all), the more you have to explain in your comments.

Comments also function as a SUMMARY of what the code does.

A file should always have a summary at the top. A function more than a couple lines long should always have a summary explaining what it does.

In the real world, people don't have time to read your 5,000 lines of code -- they need to be able to jump in, make a change, and not break things. Comments are very important for this.

While the recommended practice is not to describe what the code does, I let go of that practice a while ago. Most of our projects are polyglot and our new hires don't know what a section does in an unfamiliar language. That takes time. The learning process is expedited by describing what the code does. Moreover, I tend to pseudocode the non-trivial sections in comments anyway. There's no need to throw that away.

"comments as a bad smell"

I don't understand this. You get two orthogonal things, code quality and comments quality, and you tie them together for some reason - but they are still orthogonal.

Good code that is well documented is always a much better thing than a good code that is not documented (with comments). And bad code with good comments is still much better than bad code without comments at all.

On the other hand bad comments are just bad.

I can't help but think that people who consider comments a "smell" do so because they can't write good comments. Well, writing good comments is hard, but that doesn't mean we shouldn't try.

Well part of the idea is that if you have to write so many comments, your code might be unnecessarily complex or hard to understand. Often, straightforward code is better than clever code.

Also, having paragraphs of comments is often distracting and makes it really difficult to skim through files to find things. To me it seems a little excessive to have two paragraphs of comments for a 5 line method without a good reason.

I know that you often need to do that for RDoc or YARD or other documentation generators, and documenting mature code can be good, but it might be a little overkill for experimenting around.

That being said, there's absolutely nothing wrong with having the ability to do it and make it look pretty if you want to.

In other news: Emacs is better than Vim and static typing is better than dynamic typing.

What I'm trying to say is that discussion about comments in code is useless unless it's based on real code - and then it's still largely a matter of one's habits and expectations. In case of your post here, for example, I can already see that we are talking about different things and that we have very different ways of working with code. To convince you that good comments are good I'd have to first explain to you how I work with code already written, then how I write code, then how I write comments and then define what a "good" comment is. I'm positive that I would succeed, however I have no time now to attempt this and you're probably not that interested either.

Anyway, I'm much more productive when working with heavily commented (with good comments) code. I don't like the loss of productivity I see when working with code without comments. It's entirely possible that you're working in a way that doesn't benefit from comments, and it's nothing bad in itself, but you shouldn't use this as an argument against comments in code.

On a project I am working on, I write all my public interfaces in literate programming style so it can doubles as comprehensive API documentation to put up on GitHub pages or websites or printed for sending to 3rd parties without me having to carefully correlate code and a separate document (they'are already there together.)

On other, more private parts of the code, I just write it normally, with minimal comments.

Another benefits is that, when you change the code, the relevant documentation is right there next to it. I find this minimizes the chance of having an outdated documentation and make it very simple and convenient to update the docs when I update any public interfaces.

"..most of the programmers I socialise with tend to see comments as a bad smell.."

I think it really depends on the language and context. Most of my development these days is native iOS on the client side, and Node.js via CoffeeScript on the server. The more verbose a language or API is, the more self-documenting it is. On the other hand, the more concise a language is, the more documentation it requires. I find that I need very little documentation to write maintainable Cocoa code. CoffeeScript is different story though. I can come back to 3-4 month old CoffeeScript code and have difficulty remembering what it did. It needs more documentation to have the same readability as my Cocoa code. Not just the why, but also the how. Literal CoffeeScript seems to be a great solution to this problem. I can't wait to use it. Thanks jashkenas!

Comments give you a way to describe your analysis of the problem. They also give you a way to describe how the code solves the problem.

If the code doesn't need any human problem analysis, perhaps it's redundant? Could a higher-level analysis have solved the entire class of problems?

    Beyond any educational benefit, what do you see as the advantages of programming 
    in this way?
For me, literate programming has been exceptional for organizing my thoughts, and preventing me from thinking myself in loops, or hitting a wall of decision paralysis. Being able to express what I'm trying to do in English, Spanish, Mandarin, etc., is a prerequisite to being able to express it in Ruby, Python, or CoffeeScript.

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact