Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free.

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

Just out of curiosity, I started wondering whether a language which doesn't allow comments would yield more readable code as you would have be forced to write self-commenting code.

Then again, you could write just as bad code as before because you just don't care. But what's your opinion?

share|improve this question

closed as not a real question by Adam Nov 25 '11 at 22:32

It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form. For help clarifying this question so that it can be reopened, visit the help center.If this question can be reworded to fit the rules in the help center, please edit the question.

Do you think there's a difference between a language that doesn't allow comments and developers who don't use them? – Jeremy Heiler Jan 11 '11 at 15:38
The idea that disallowing comments would force developers to write more self-documenting code is absurd. – Adam Crossland Jan 11 '11 at 15:47
@Jeff that is an IDE/editor feature not a langugae feature IMHO – jk. Jan 11 '11 at 17:05
im not sure it is possible to force developers to do anything – jk. Jan 11 '11 at 18:15
@Adam @jk01 : they even have a language that forces developers to indent the code in a specific way ;-) – Joris Meys Jan 11 '11 at 20:43

16 Answers 16

I think programmers would figure out another way to add comments...

string aComment = "This is a kludge.";
share|improve this answer
I like how this "comment" has multiple layers – Logan Capaldo Jan 11 '11 at 15:45
An added benefit is that it will go in the binary, so you can see the comments there too! Makes reverse engineering much simpler. – user1249 Jan 11 '11 at 15:48
You're right. We'd have to use #ifdef statements instead. – James Jan 11 '11 at 19:03
This is probably the best example of "programming into a language" as opposed to "programming in a language" that I've ever seen. =) – gablin Jan 11 '11 at 20:44
In MOO there is support for comments, but all programs are parsed for storage and unparsed for display so comments are lost. The idiom for persistent comments is string literals ala "this is a comment"; – Ben Jackson Jan 11 '11 at 22:19

I don't think it's that simple:

even in well-written, self-documenting code, there are legitimate situations where you should write comments.

share|improve this answer
+1 for comments being more than a simple narration of what code is doing. Even the best 'self-documenting code' needs to have comments for elaboration of many things. Often times, code will have external dependencies, input assumptions, caveats, improvable areas, known vulnerabilities and countless other things that are never otherwise acknowledged. Comments have many uses. – Adam Crossland Jan 11 '11 at 16:04
Exactly. How do you register "intent" or "why" or "proof of correctness" without comments? – S.Lott Jan 11 '11 at 16:25
Agreed, comments should be "Why" and not "What". Anyone who can't get the What from the code should not be reading it. – Matthew Read Jan 11 '11 at 16:33
@Matthew: To be fair, you can easily write code that isn't easily deciphered. But yes, readable code is the best source for "what". – delnan Jan 11 '11 at 16:49

Supposing you're a perfect programmer (which you're not, but let's just suppose)...

There's lots of nonobvious effects that can happen in code when you're interfacing with stuff you didn't write. For example, there can be design flaws someone else's library, or (if you're a kernel developer) in someone else's hardware. Having comments to explain why you used particular kludge in a particular place can be essential to understanding the code, and making sure the kludge isn't removed (breaking things).

share|improve this answer

It is hard for me to wrap my mind around the idea that removing options from a language would somehow make programs written in said language better. Comments are not mandatory, and writing self documenting code is not as well.

There is no substitute for good development practices.

share|improve this answer

In theory, COBOL was originally designed in such a way that it was meant be self documenting enough that even non-developers (i.e. supervisors) could review code that was written and determine what was going on. However, in practice, as a program grows more complex, it is difficult to understand everything that is going on solely through the code.

While removing comments might force some developers to write code that is better at self documentation, there are still developers out there that write poorly documented code (i.e. variable names of a, b, c, etc) and it is those habits that people need to be trained out of of. In those cases, removing comments wouldn't affect those developers and may hinder the efforts of other developers to explain complex pieces of code.

share|improve this answer
I'm reading some code now with this: argument = 3.0; aa = sqrt( argument ); bb = f( aa ); Sigh. – S.Lott Jan 11 '11 at 16:38
Cobol is a special language. But the "." Operator is evil!!! It kind of break the syntax of a sentence. – Loïc Faure-Lacroix Jan 12 '11 at 1:24

Every program gets written to implement functional requirements that are outside the program, whether written down or just in someone's head.

I think the most essential function of comments is to establish a mapping between the requirements and the code. The reason the mapping is needed is to permit incremental changes. When a change to the requirements occurs, it is necessary to make corresponding changes to the code, if the code is to remain a solution to the requirements. The comments serve as a roadmap for the changes.

If the language is an ideal domain-specific-language (DSL) perfectly adapted to the problem being solved, then the mapping should be a simple isomorphism, and comments would not be necessary. The source code would simply state the problem, and nothing else would need to be said. The solution of the problem would be buried in the implementation of the language.

Since the languages we work in are not such DSLs, and will remain so for some time, we still need comments. It's a matter of degree. Sometimes the problem is a good match to the language at hand, but usually not.

See also...

share|improve this answer

I work somewhere which doesn't allow inline comments (i.e. you can only have comments at the top of functions). No, it doesn't make the code easier to read. It makes it orders of magnitude worse.

share|improve this answer
Assuming there's no limit to the number of methods, why don't you just refactor your blocks of code out into applicable methods and then give the methods descriptive names (or more comments, in your case)? In most "good" code I've seen, methods are rarely longer than about 10 lines, and it's quite obvious what it does. – Scott Whitlock Jan 11 '11 at 21:43
@Scott - I'm a firm advocate that code should be self-documenting and that inline comments are to be avoided, but explicitly forbidding them is overkill. – Jason Baker Jan 12 '11 at 0:42
@Jason - I agree with you, but I just don't agree with the idea that without inline comments it's "orders of magnitude worse". – Scott Whitlock Jan 12 '11 at 2:26
@Scott: You get a lot of comments like "the reason we do the weird null check on line 37 is ..." and then you have to flick your eyes between the code and the comments. It would be much easier to just have that comment above line 37. – Xodarap Jan 12 '11 at 15:19

I avoid commenting code, and it works.

I avoid all in-code (inline or stream) comments in favor of docblock + meaningful varables + spartan programming, and it works.

And yes, I know docblocks are technically comments, still, they are actually complementary to code, not intrusive and "standardized"... everything a common comment is not.

What I think could work as a substitute of comments: a standardized docblock language/syntax/idiom, something like annotations in java.

share|improve this answer
"a standardized docblock language/syntax/idiom" : Wouldn't doxygen work for this? – sleske Jan 11 '11 at 22:46
Doxygen is a documentation tool, same as phpdocumentor and the thing that generates the Java documentation from javadoc (homonim?). What I mean is that the language/syntax/idioms was part of the programming language itself, and not a comment that has to be parsed for tags/properties. – dukeofgaming Jan 12 '11 at 4:31
So, you avoid comments by calling them something else. – Nate C-K Sep 7 '11 at 17:46

Not only would it not affect quality- as others have observed, it would actually be really annoying.

I'm sure most of us have done something like this from time to time:

foreach ( myObject obj in SomeList )
    Debug.Writeline( obj.Name );
//  for some reason this isn't working
//  obj.SetArielPotency( setting );
//  obj.DoSomeProcess();       

How irritating would it be if you couldn't comment out a few lines of code to figure out where that bug is coming from?

Regardless of comments on how code operates, simple practical things like that or dropping in a convenient TODO note are things that make it easier to fix minor problems and remember what we were doing when we started writing the code.

share|improve this answer

Comments are like a book summary. Sure, you can understand everything by reading code, but why on earth do you want to read a whole page when it could be summarized in one commented line?

share|improve this answer
If you can summarize it in one line, you can name a function or method descriptively enough to explain what it does. – Scott Whitlock Jan 11 '11 at 21:40

While I agree with the other answers that even self-documenting code needs comments, that is only relevant for current languages.

I think the real question is, "Is it possible to design a new programming language that doesn't need comments?" It would need to be pretty high level with a great deal of abstraction. Every statement and function would be forced to be readable via the language's syntax.

share|improve this answer
Literate programming offers a language that doesn't need comments. You write your document, which includes all of the necessary explanation, support, proof, intent, trade-offs, kludges, etc., as well as code. Since the code is not intended to stand alone, it works nicely. – S.Lott Jan 11 '11 at 19:35
@DisgrunteldGoat : forget about that. You'd have to start from a particular language, and I speak only 5. All the rest of the languages I'd be as lost as you would be in Dutch. – Joris Meys Jan 11 '11 at 20:46
Re second paragraph: of course you can. Take all current languages that offer comment support, and remove comment support. If these languages needed comments, then they would be in the compiled code or the interpreter would do something other than ignore them. – Kit Jan 12 '11 at 4:49

Undisciplined programmers will write bad code, no matter the language.

Intriguing that python, which just has private by convention (_-prefix), does not make any effort to police this, and much fine code is still being written.

Rant: Sometimes I think more permissive langugages would force more people to learn to code properly, rather than the reverse (i.e. Java's only-one-way and damned you be if you want to think of functions as first-class objects).

share|improve this answer

I will guess: probably not. Why? Because you'd have to encode "why" as a formalism in the language and because "why", whether encoded in language or comment-in-language is underused by programmers anyway.

share|improve this answer

Code can certainly be self-commenting in explaining what it is doing, but it is not always possible for code to explain why it is doing it. That is where comments are most needed.

If, for example, a section of code is needed to comply with a specific regulation, how do you explain that without a comment? If the algorithm used by a particular piece of code is described in a paper written in 1998 by M. Matsumoto and T. Nishimura, how do you explain that without a comment? If an algorithm doesn't provide exactly the optimum functionality but makes a very specific justified compromise that may cause future issues if other code is changed, how do you explain that without a comment?

What if one section of code was audited by an independent auditor so it cannot be modified without invalidating that audit and the code is used to build a product whose compliance with that audit is required by your customers. How do you indicate that without a comment?

share|improve this answer

I've always thought that it might be nice to have a one-word comment so that if you prefixed a word with a symbol (let's say a colon), that word would be ignored. That way, you could have say a lisp that it only allowed one-word comments inside an s-expression. For instance, you could turn this:

(if (= x y)

...into this:

(if (= x y)
    :then x
    :else y)

If you absolutely have to, you could chain multiple one-word comments to form an inline comment:

(if x :Remember, :x :could :be :nil!

Of course, this is a pain to type. In fact, that's the point. It encourages you to use inline comments sparingly and keep them short and to the point. But I have a feeling that I'd have a difficult time convincing anyone to use the language.

share|improve this answer
It also makes it hard to read, which defeats the use of comments to make code more readable. – Nate C-K Sep 7 '11 at 17:48

This is double-or-nothing. Some programmers do nothing to make code readable. Not allowing comments will reinforce this. Some programmers write good comments, even if they would be even better if they were code refactoring rather than comments -- removing comments may force them to do the better refactoring.

Reasons why this is a good idea: - None

Reasons why this is a bad idea: - There are many more atrocious programmers than good-but-not-great programmers - There should almost always be some comments for weird gotchas, summaries, etc - Even if you eschew comments, you will probably use comments as a stage on the way: throw in a comment when you're writing something, and then come back and refactor it away. But you can't always do it right immediately because you're still learning. - It will encourage people to work round it - Who would use it? People who write unreadable code and want an excuse (bad) and people who are already enamoured of the idea (who can just "not write comments" to start with). If this is what you want, just write a coding standard showing how you want people to do it.

Reasons where this may be relevant - Where it could be useful is as part of a system to make "not commenting" better, eg. a language or IDE which has good support for something-better-than-comments and as part of its pitch, eschews comments. I don't know how it would work, but it's a good point worth at least thinking about.

share|improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.