Clever JavaScript does not mean simple or readable

I ran across this code recently:

<h<?php echo (is_singular()) ? '1' : '2'; ?>>

Which is just an absurd example of being too clever. Moving the HTML tags into the output makes the code's purpose much clearer:

<?php echo (is_singular()) ? '<h1>' : '<h2>'; ?>

Is it longer? Sure. But it's also much easier to read.

These days I try to be less clever when writing code.

But we’ve become obsessed as an industry with brevity and clever code

As an industry we most certainly have not. Ad hoc self taught or 'MVP worshipping' javascript programmers perhaps. As an industry the core principle of readable code is the strongest it has ever been. Gone are the days of trying to guess whether code is a C code golf competition entry or production code, and there is that much support for easy to read code out there that there is literally no excuse.

There is also that idea of people spruiking 'performant' code - again, the rest of the industry has recognised premature optimisation as REALLY dumb. Developer time is so much more expensive than CPU time.

Personally, I waffle on this a lot. I prefer elegant code, which, in high level programming languages, is often also concise. There is often a tension between brevity and clarity, but I’d argue that brief, but inelegant code is not something to aspire to. Often times, I find that clever code is concise because it abuses language features, or uses inscrutable identifiers. Whereas, elegant code is concise because it is a reduction of the computation to the minimum language constructs necessary to express the computation.

E.g., this Python function is something I use all the time, and I think it is quite elegant.

def ngrams(iterable, n=1): 
    """Generate ngrams from an iterable 
     
    l = range(5) 
    list(l) -> [0, 1, 2, 3, 4, 5] 
    list(ngrams(l, n=1)) -> [(0,), (1,), (2,), (3,), (4,)] 
    list(ngrams(l, n=2)) -> [(0, 1), (1, 2), (2, 3), (3, 4)] 
    list(ngrams(l, n=3)) -> [(0, 1, 2), (1, 2, 3), (2, 3, 4)] 
     
    """ 
    return zip(*(iterable[i:] for i in range(n)))              

Is this brief? Yes. Is it clear? Only if you are familiar with the Python idioms being leveraged here. Is it clever? I’m not sure. Is it elegant? I think very much so. You could rewrite this function to be more clear, but the docstring makes it clear, and if you are comfortable with Python list comprehensions, Python’s built-in zip and the interaction of the "splat" operator (*) for unpacking argument lists with zip, then it becomes clear, but anyone not familiar with Python will likely say this is impenetrable.

Here’s a more clear version, but I think it’s less elegant:

def ngrams(iterable, n=1): 
    """Generate ngrams from an iterable  
      
    l = range(5)  
    list(l) -> [0, 1, 2, 3, 4, 5]  
    list(ngrams(l, n=1)) -> [(0,), (1,), (2,), (3,), (4,)]  
    list(ngrams(l, n=2)) -> [(0, 1), (1, 2), (2, 3), (3, 4)]  
    list(ngrams(l, n=3)) -> [(0, 1, 2), (1, 2, 3), (2, 3, 4)]  
      
    """ 
    if n == 1: 
        yield from ((v,) for v in iterable) 
    else: 
        for i, v in enumerate(iterable[:-n+1]): 
            yield tuple(iterable[i:i+n]) 

I think brief, elegant code, with good documentation, should be the ultimate goal. Some will argue that elegant code is self-documenting. This is where I waffle. If you don’t understand the way this function works, at least you can treat it like a black box and understand what it does based on the docstring. Writing in-line functions without comments or documentation is what people deride as 'write-only' code, and I think even clever code can be useful if it is well documented. I.e., the next person who comes along (maybe even the author, months from now) and tries to read a clever, undocumented bit of code is likely going to have to remove that code and start from scratch if they have to make any changes.