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?
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 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.
Will try literate coffeescript next time I use it.
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.
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.
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.
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.
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 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.
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!
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?