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?
I think programmers would figure out another way to add comments...
string aComment = "This is a kludge.";
"this is a comment";
Commented
Jan 11, 2011 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.
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).
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.
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.
argument = 3.0; aa = sqrt( argument ); bb = f( aa ); Sigh.
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.
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.
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.
doxygen work for this? en.wikipedia.org/wiki/Doxygen
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.
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?
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.
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).
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.
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?
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)
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.
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.