When code is a maze, smart developers make maps (2025)

When code is a maze describes my 1988 IOCCC entry [1]

    char*M,A,Z,E=40,J[40],T[40];main(C){for(*J=A=scanf(M="%d",&C);
    --            E;             J[              E]             =T
    [E   ]=  E)   printf("._");  for(;(A-=Z=!Z)  ||  (printf("\n|"
    )    ,   A    =              39              ,C             --
    )    ;   Z    ||    printf   (M   ))M[Z]=Z[A-(E   =A[J-Z])&&!C
    &    A   ==             T[                                  A]
    |6<<27<rand()||!C&!Z?J[T[E]=T[A]]=E,J[T[A]=A-Z]=A,"_.":" |"];}

[1] https://tromp.github.io/pearls.html#maze

Smart developers don’t write mazes.

> In code, comments are our signposts

No. Naming and good architecture are. Intuitive folder trees. Concise docs. Clear separation of concerns such that naming can suffice.

The more comments you need to ‘map’ your code, the worse of a job you’ve done.

> Typically keep comments on a single line without line breaks — if a comment is useful, developers will scroll to read them, if it’s not they can easily scroll past it.

Disagree. Personally that sounds like a massive barrier to reading the comment to me. Limited width column text is generally regarded as easier to read, make your comments easier to read. Especially as I probably have the code open in a limited width window, as that's what I expect from code.

I disagree with the overall sentiment of this article. I wouldn't say comments are never useful, because they certainly can be. But once verbose commenting becomes the norm, people (and now especially LLMs) will overuse them, making the code unnecessarily obtuse and difficult to read. And the point about maintenance is real.

There are also a couple of 'pointless' statements in the article itself:

> "Use a combination of in-line and standalone comments, depending on the situation"

isn't that just every kind of comment?

Once again I am asking, who is this person and why do they think they are qualified to tell me what's best?

Sounds good. I've lost count of how many mazes I've made. Just call me the Architect of the Labyrinth.