How to Solve the Problem of Nested Comments in Java, C++, Python, and C

ccommentsjavapython

It appears in not just one language that comments can't be nested. Do you have a good solution for this problem? One workaround in C/C++ and Java is to only use the single-line comment but it becomes impossible then to comment out a larger block. I'm facing something like this:

</li><!--
                <li><!-- Save -->

So I must manually go through and edit the comments. Can you advice how we should handle this, in many languages? I'm not sure but maybe python has a solution for this with the ''' way that might be able to include a # comment in python?
`

Best Answer

The best solution is, obviously, to just not nest your comments. Nested comments are usually a sign that you are using comments wrong. The most common example is commented-out code that contains comments itself, and the fix is to remove the code instead of commenting it out.

That said, many programming languages have more than one type of comment syntax, and you can use this fact to nest at least one level deep. For example, in Java:

/* This is commented out!
Foo.bar.baz();
// And now for something completely different...
Quux.runWith(theMoney);
*/

Also, in many languages, at least one type of comment is kind-of-nestable; in C-like languages, line comments inside line comments are ignored:

// some_commented_out(code);
// // This is a comment inside the comment!
// // Still inside the nested comment.
// some_more_code_in(outer_comment);

Most IDEs support commenting entire blocks of code with line comments in one action, and they handle this kind of commenting style correctly. The same example in Python:

# some_commented_out(code)
# # This is a comment inside the comment!
# # Still inside the nested comment.
# some_more_code_in(outer_comment)

Often, coding standards for a particular project have rules about which comment style to use when; a common convention is to use block comments (/* */) for method and class documentation, and inline comments (//) for remarks inside method bodies and such, e.g.:

/**
 * Helper class to store Foo objects inside a bar.
 */
public class Foobar {
    /**
     * Stores a Foo in this Foobar's bar, unless the bar already contains
     * an equivalent Foo.
     * Returns the number of Foos added (always 0 or 1).
     */
    public int storeFoo(Foo foo) {
        // Don't add a foo we already have!
        if (this.bar.contains(foo)) {
            return 0;
        }
        // OK, we don't have this foo yet, so we'll add it.
        this.bar.append(foo);
        return 1;
    }
}

With such a style, it is unlikely that you'll ever need to nest /* */ comments (if you have to temporarily disable entire methods or classes, renaming them work just as nicely, if not better); and // comments do nest, at least with a little help from your IDE.

Finally, to disable code, you have other options in many programming languages; for example, in C, you can leverage the preprocessor:

this_is(activated);
#if 0
this_is(!activated);
/* Comments inside this block don't really nest, they are simply removed
   along with the rest of the block! */
#endif

In dynamic languages, you can often just use regular if statements instead:

<?php

if (0) {
   // This should never run... 
   some_stuff_that_should_never_run();
}

However, unlike the CPP example, this strategy requires the source file as a whole to be syntactically valid, so it's by far not as flexible.

And finally, there are at least some languages that allow for nested comments. In case you're interested, wikipedia has a nice comparison chart.

Comment Types

For the brief version... I use comments for:

trailing comments explaining fields in data structures (apart from those, I don't really use single line comments)
exceptional or purpose-oriented multi-line comments above blocks
public user and/or developer documentation generated from source

Read below for the details and (possibly obscure) reasons.

Trailing Comments

Depending on the language, either using single-line comments or multi-line comments. Why does it depend? It's just a standardization issue. When I write C code, I favor old-fashioned ANSI C89 code by default, so I prefer to always have /* comments */.

Therefore I would have this in C most of the time, and sometimes (depends on the style of the codebase) for languages with a C-like syntax:

typedef struct STRUCT_NAME {
    int fieldA;                /* aligned trailing comment */
    int fieldBWithLongerName;  /* aligned trailing comment */
} TYPE_NAME;

Emacs is nice and does that for me with M-;.

If the language supports single-line comments and is not C-based, I will be more enclined to use the single-line comments. Otherwise, I'm afraid I've now taken the habit. Which isn't necessarily bad, as it forces me to be concise.

Multi-Line Comments

I disagree with your precept using single-line comments for this is more visually appealing. I use this:

/*
 * this is a multi-line comment, which needs to be used
 * for explanations, and preferably be OUTSIDE the a
 * function's or class' and provide information to developers
 * that would not belong to a generated API documentation.
 */

Or this (but I don't that often any more, except on a personal codebase or mostly for copyright notices - this is historical for me and comes from my educational background. Unfortunately, most IDEs screw it up when using auto-format):

/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/

If need really be, then I would comment inline using what I mentioned earlier for trailing comments, if it makes sense to use it in a trailing position. On a very special return case, for instance, or to document a switch's case statements (rare, I don't use switch often), or when I document branches in an if ... else control flow. If that's not one of these, usually a comment block outside of the scope outlining the steps of the function/method/block makes more sense to me.

I use these very exceptionally, except if coding in a language without support for documentation comments (see below); in which case they become more prevalent. But in the general case, it really is just for documenting things that are meant for other developers and are internal comments that really need to really stand out. For instance, to document a mandatory empty block like a "forced" catch block:

try {
    /* you'd have real code here, not this comment */
} catch (AwaitedException e) {
    /*
     * Nothing to do here. We default to a previously set value.
     */
}

Which is already ugly for me but I would tolerate in some circumstances.

Documentation Comments

Javadoc & al.

I'd usually use them on methods and classes to document versions introducing a feature (or changing it) especially if that's for a public API, and to provide some examples (with clear input and output cases, and special cases). Though in some cases a unit case might be better to document these, unit tests are not necessarily human readable (no matter what DSL-thingy you use).

They bug me a bit to document fields/properties, as I prefer trailing comments for this and not all documentation generation framework support trailing documentation comments. Doxygen does, for instance, but JavaDoc doesn't, which means you need a top comment for all your fields. I can survive that though, as Java lines are relatively long anyways most of the time, so a trailing comment would creep me out equally by extending the line beyond my tolerance threshold. If Javadoc would ever consider improving that, I'd be a lot happier though.

Commented-Out Code

I use single-line for one reason only, in C-like languages (except if compiling for strict C, where I really don't use them): to comment-out stuff while coding. Most IDEs will have toggle for single-line comments (aligned on indent, or on column 0), and that fits that use case for me. Using the toggle for multi-line comments (or selecting in middle of lines, for some IDEs) will make it harder to switch between comment/uncomment easily.

But as I'm against commented-out code in the SCM, that's usually very short lived because I'll delete commented-out chunks before committing. (Read my answer to this question on "edited-by in line comments and SCMs")

Comment Styles

I usually tend to write:

complete sentences with correct grammar (including punctuation) for documentation comments, as they are supposed to be read later on in an API doc or even as part of a generated manual.
well-formatted but more lax on punctuation/caps for multi-lines comment blocks
trailing blocks without punctuation (because of space and usually because the comment is a brief one, that reads more like a parenthesised statement)

A note on Literate Programming

You might want to get interested in Literate Programming, as introduced in this paper by Donald Knuth.

The literate programming paradigm, [...] represents a move away from writing programs in the manner and order imposed by the computer, and instead enables programmers to develop programs in the order demanded by the logic and flow of their thoughts.2 Literate programs are written as an uninterrupted exposition of logic in an ordinary human language, much like the text of an essay[...].

Literate programming tools are used to obtain two representations from a literate source file: one suitable for further compilation or execution by a computer, the "tangled" code, and another for viewing as formatted documentation, which is said to be "woven" from the literate source.

As a side note and example: The underscore.js JavaScript framework, notwithstanding non-compliance with my commenting style, is a pretty good example of a well-document codebase and a well-formed annotated source - though maybe not the best to use as an API reference).

These are personal conventions. Yes, I might be weird (and you might be too). It's OK, as long as you follow and comply to your team's code conventions when working with peers, or do not radically attack their preferences and cohabitate nicely. It's part of your style, and you should find the fine line between developing a coding style that defines you as a coder (or as a follower of a school of thought or organization with which you have a connection) and respecting a group's convention for consistency.

Python Functional Programming – Exception Handling Techniques

First of all, let's clear up some misconceptions. There is no "bottom value". The bottom type is defined as a type that is a subtype of every other type in the language. From this, one can prove (in any interesting type system at least), that the bottom type has no values - it is empty. So there is no such thing as a bottom value.

Why is the bottom type useful? Well, knowing that it's empty let's us make some deductions on program behavior. For example, if we have the function:

def do_thing(a: int) -> Bottom: ...

we know that do_thing can never return, since it would have to return a value of type Bottom. Thus, there are only two possibilities:

do_thing does not halt
do_thing throws an exception (in languages with an exception mechanism)

Note that I created a type Bottom which does not actually exist in the Python language. None is a misnomer; it is actually the unit value, the only value of the unit type, which is called NoneType in Python (do type(None) to confirm for yourself).

Now, another misconception is that functional languages do not have exception. This isn't true either. SML for example has a very nice exception mechanism. However, exceptions are used much more sparingly in SML than in e.g. Python. As you've said, the common way to indicate some kind of failure in functional languages is by returning an Option type. For example, we would create a safe division function as follows:

def safe_div(num: int, den: int) -> Option[int]:
  return Some(num/den) if den != 0 else None

Unfortunately, since Python doesn't actually have sum types, this isn't a viable approach. You could return None as a poor-man's option type to signify failure, but this is really no better than returning Null. There is no type-safety.

So I would advise following the language's conventions in this case. Python uses exceptions idiomatically to handle control flow (which is bad design, IMO, but it's standard nonetheless), so unless you're only working with code you wrote yourself, I'd recommend following standard practice. Whether this is "pure" or not is irrelevant.