Are comments necessary for a programming language?

Question

After some stupid musings about Klingon languages, that came from this post I began a silly hobby project creating a Klingon programming language that compiles to Lua byte-code. During the initial language design phase I looked up information about Klingon programmers, and found out about this Klingon programming rule:

A TRUE Klingon Warrior does not comment his code!

So I decided my language would not support commenting, as any good Klingon would never use them.

Now many of the Klingon ways don't seem reasonable to us Human programmers, however while dabbling with the design and implementation of my hobby language I came to realize that this Klingon rule about commenting is indeed very reasonable, if not great.

Removing the ability to comment from a programming language meant I HAVE to write literate code, no exceptions.

So it got me wondering if there are any languages out there that don't support comments?

Is there are any really good arguments to not remove commenting from a language?

Edit: Any good examples of comments required?

---

P.S.> My hobby language above is partially silly anyways, so don't focus too much on my implementation, as much as the concept of comments required in general

Answer 1

You might think that developers writing in your language will make an extra effort to write clear code but the onus will actually be on you to design a language that's so expressive that it doesn't need to be commented. Hell, not even English is like that (we still parenthesize!). If your language isn't so designed it may very well be as usable as Brainfuck and enjoy the popularity and respect of Brainfuck.

Should I add links or are links considered commentlike?

Besides, people will find ways to add comments if they need to by highjacking strings and misusing variable names (that do nothing other than stand in for comments). Have you read Godel Escher Bach?

Answer 2

I think the question may become how self-contained would the language without comments be? If for example, it compiles down to DLLs that get used within other code, then how does one know anything beyond the function signature in terms of what it requires, changes and returns? I wouldn't want to have function names being dozens of characters to try to express what may be very easily done with comments above the function that can be used as documentation within something like the Object Browser within Visual Studio for example.

Answer 3

Languages need comments. At least 95% of comments can be replaced by clearer code but there are still assumptions you need to document and you absolutely need to document if there's some external problem you are working around.

I never write a comment without first considering if I can change the code to eliminate the need for it but sometimes you can't.

Answer 4

I am not sure I agree with the "Have" in the statement "Removing the ability to comment from a programming language meant I HAVE to write literate code, no exceptions", since it is not as if all code is documented. My guess is that most people would write unreadable code.

More to the point, I personally do not believe in the reality of the self-explanatory program or API in the practical world.

My experience from manually analyzing the documentation of entire APIs for my dissertation suggests that all too often you would have to carry more information than you could convey in the signature alone. If you eliminate interface comments from your language, what are the alternatives? No documentation is not an option. External documentation is less likely to be read.

As for internal documentation, I can see your point in wanting to reduce documentation to convince people to write better. However, comments serve many collaboration and coordination purposes and are meant to raise awareness of things. By banishing these details to extenral locations, you are reducing the chances that they come to a future reader's awareness, unless your tooling is great.

Answer 5

In general comments are a wart that indicates poor design, especially long rambling comments where its clear the developer didn't have a clue what the heck they where doing and tried to make up for it by writing a comment.

Places where comments are useful:

• Leaving a ticket number next to a fix so future programmers can understand business requirements
• Explaining a particularly tricky hack
• Commentary on business logic for a piece of code
• Terse descriptions in API docs so a third-party can use your API

In all circumstances programmers should endeavor to write code that is descriptive and NOT write comments that describe poorly written code. That being said I think there are plenty of valid reasons that languages should and must support comments.

Answer 6

Your code has two distinct audiences:

• The compiler
• Human beings like us

If you choose to remove comments altogether, the assumption you are taking is that you will be catering only to the compiler, and to nothing else.

Of course you, being Klingon, may not need comments because you are not human. Perhaps you could clearly demonstrate to us your ability by speaking in IL instead?

Answer 7

Do not comment WHAT you are doing, but WHY you are doing it.

The WHAT is taken care of by clean, readable and simple code with proper choice of variable names to support it. Comments show a higher level structure to the code that can't be (or is hard to) show by the code itself.

Answer 8

While it's true that humans need to be able to comment code, it is not absolutely necessary that the language directly support commenting: for most languages, it would be trivial to write a script that deletes one line comments (for example, all lines beginning with '#' or some other character) then runs the compiler.

Actually, though, I am surprised and disappointed to learn that even my favorite esoteric programming languages support comments: Brainf**k and Whitespace. These languages are meant to be hard to read, so it seems like they shouldn't support commenting. (As opposed to my other favorite esoteric language: LOLCode, which is meant to be self-documenting, in lolcats-speech)

I would dissent from the other answerers on this point: I say, be true to your vision of a Klingon programming language, and do not support comments!

Answer 9

It will be a bad idea to remove the commenting facility altogether. Surely developers must learn to write code with minimum comments i.e. to write self documenting code but there a lot of cases where one has to explain why something is being done the way it is. Consider the following cases:

• a new developer might start maintaining the code and the original dev has left/ out of the project
• a change in specification or market requirement leads to something that is counter intuitive
• copy right notice especially if open source (some open source libs require you to do this)

It is also my experience that new programmers tend to comment more and as they develop expertise their code tends to become self documenting and concise. In general comments should be about WHY and not HOW or WHAT.

Answer 10

Of course!!

The main reason is novice developers. Not everyone knows how to write literate code. Actually there are millions out there don't get a NullPointerException when they see one.

We all start at some point.

But if you're targeting to "expert" developers only, why bother in the language in first place. You should be using butterflies !!! That's what real developer use!

Comments is a must, try to make it harder if you wish ( like using #//##/ sequence to create a comment or something like that ) but don't leave it out.

:)

Answer 11

NO -- there is not a single programming language out there that requires comments.

The language is for the computer. The comments are for the humans. You can write a program with 0% comments. It'll execute, rightly or wrongly. You can't write a program with 100% comments. It'll either not compile -- no main(), etc. -- or, for scripting languages, do exactly nothing.

And, besides, real programmers don't comment their code. Just like Klingons.

Answer 12

A point against comments is that they tend to often fall out of date with the code. Any time you add a redundancy, you're risking this sort of inconsistency.

There's actually some interesting research that I've seen when a group used NLP to analyze locking comments in some large system and then compare them to the results of static analysis and were able to fix a few bugs that way.

Answer 13

Ugh, not being able to quickly comment out a line (or lines) during testing sounds annoying to me, especially when scripting.

Answer 14

Are comments necessary for a programming language?

No. In the grand scheme of things a compiler couldn't care less about a comment and just wants code to grind down to a lower common denominator.

Is it useful for a programming language to provide a commenting construct?

Yes. Comments are very useful for a programmer and not just to fake like they know what they are doing, but in debugging and usefully documenting as well.

Answer 15

While I agree with Uri's responses, I too have made a language with no comments. (ichbins.) The language was to be as simple as possible while still being able to express its own compiler cleanly; since you can do that without comments, they got jettisoned.

I'm working off and on on a revision that does support commentary, but a bit differently: literate-programming style with code nested in text instead of comments embedded in code. It might also get examples/test-cases later as a first-class language feature.

Good luck with the Klingon hacking. :-)

Answer 16

Isn't literate programming as much comment as it is code? Certainly, much of what I've seen of literate programming has as much explanation as code, if not more comment.

Answer 17

I agree with you that nicely written code does not need any comments as "Code is only good documentation available to programmer. However this is very ideal condition, not everyone writes good code all time. So to make poorly written code good in future comments are required.

Answer 18

I can't tell you how thankful I am for Javadoc - which is really simple to set up within comments. So that's at least one sense in which comments are useful.

Answer 19

I once wrote a VB app (a silly board game inspired by Monopoly) without any comments. But I did that just to piss off my teacher, who had told us comments were for "whatever we found relevant, so we could remember it later".

Answer 20

No, of course a language doesn't have to have commenting. But a (useful) program does have to have comments... I don't agree with your idea that literate code lacks comments. Some very good code is easily comprehensible with comments, but only with difficulty without.

Answer 21

While all source code is copyrighted by default. It is often nice to:

1. remind the person reading the source code that it is subject to copyright

2. tell people what the licensing terms are for that source code file

3. tell them whether or not they are looking at a protected trade secret

Unfortunately, without comments, it is difficult to do this.

Answer 22

You don't need a single assertion in your code because, in release mode, they're all gone. But when C++ didn't have assertions built-in, someone wrote the assert macro to replace it.

Of course you don't need comments, either, for more or less the same reason. But if you design a language without comments, people will start doing things like:

HelperFunctionDoesNothing("This is a comment! Blah Blah Blah...");

Answer 23

I'm curious. How do you stop someone from declaring a static string containing a comment and then ignoring the variable for the rest of the func/method/procedure/battle/whatever?

var useless_comment = "Can we destroy our enemies?"
if (phasers on full) return Qapla'

Answer 24

I think the comments are required in many situations.

For instance, think of the algorithmic ones. Suppose there is a function written in C which solves the Traveling Salesperson Problem, there are wide range of techniques that can be used to deal with this problem. And the codes are usually cryptic by its nature.

Without explicitly describing the parameters and the algorithm used, by using comments, it is almost impossible to reuse this piece of code.

Answer 25

Am I the only one who comments out a couple of lines code for a number of purposes?

Answer 26

Perfect code needs zero comments. It should be simple, and understandible by complete novices.

Answer 27

Any code needs comments, I try to explain the reason for and workings of every function I write in 1 or 2 lines.

Code that explains itself only exists in a perfect world, there is always some weird hack or a reason to do something quick-n-dirty instead of the propper way. The best thing to remember is to comment WHY code does what it does, good code explains WHAT it does 99% of the time.

Write something simple, like a piece of code that can solve a Sudoku puzzle (3 reasonably simple while loops) and try reading that 3 months later. You will immidiatly find something that isn't exactly clear.

Answer 28

Can we live without comments on code? Sure, but that won't make live easier.

Answer 29

This article has a good answer:

http://www.codinghorror.com/blog/archives/000749.html

Answer 30

Code is written once, but read many times over the course of its lifetime; thus it pays to optimize for readability. Clear and consistent naming of everything from constants to classes is necessary, but may or may not be sufficient to achieve this objective. If not, fill in the gaps with comments, and maintain them as you would the code.

Answer 31

Comments are useful because they reassure the person reading your code - probably the "future you" - that you've thought about her welfare.

Answer 32

It's going to be harder than you think to make a language where comments are impossible.

if (false) {
    print("This is a comment. Chew on that, Klingons!")
}