Smart Developers Make Maps When Code Is a Maze
When code is a maze, smart developers make maps
Modern decoupled code, like ravioli code, makes it hard to understand how pieces fit together, turning codebases into labyrinths. Developers often waste hours exploring without leaving signposts. The article argues that comments and documentation are essential maps, offering practical suggestions for both to reduce future navigation time.
In most cases, we spend much more time trying to understand the code than we ever do making changes to it.
- tromp
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,"_.":" |"];}
- jorisw
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.
- jarofgreen
> 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.
- lintfordpickle
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?
- jdw64
Sounds good. I've lost count of how many mazes I've made. Just call me the Architect of the Labyrinth.