4 ms·
When code is a maze, smart developers make maps (2025)
- deleted 18d ago[deleted]
- jarofgreen 17d ago> 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.
- dozerly 17d agoWho doesn’t have soft wrapping enabled in 2026? Line breaks are irrelevant
- verdverm 17d agoWho makes assumptions about how others do things in 2026? Line breaks are apparently relevant, review agents complain about them, soft breaks are super annoying for vim motion users, opinions are still like ani
- Lindby 17d agoSoft like breaks in a code editor? That's insane
- Cockbrand 17d agoAnd so the war began. This is a bit like vim vs Emacs - everyone should be able to use their favorite setup, and the formatting should not get in the way of the engineer's preferences.
- ezrabuenk 17d agoI, in fact, do not have wrapping enabled in my IDE....
- tacomagick 17d agoYou never wrote Java I see
- xboxnolifes 17d agoJava is why I don't have line wrapping enabled. It makes code unreadable when everything needs to be wrapped.
- jarofgreen 17d agoIf line breaks really were irrelevant, the author wouldn't have felt the need to give a tip all around optimising line breaks. Personally, I would have hoped by 2026 we had better IDE's and tools for managing code in text files such that developers with different preferences for a number of characters in a column or things like how you display comments can be accommodated. Yet still teams end up arguing about what standard to use.
- someothherguyy 17d agoWhat? You don't like horizontally scrolling 6000 columns to read something? https://en.wikipedia.org/wiki/Code_folding https://en.wikipedia.org/wiki/Code_folding
- jarofgreen 17d agoYeah, if IDE's allowed code folding of comments then the authors original problem (having to scroll past comments they thought weren't useful) wouldn't be that big a deal.
- someothherguyy 17d agomany do. for example: https://www.jetbrains.com/help/idea/code-folding-settings.html#:~:text=Documentation%20comments https://www.jetbrains.com/help/idea/code-folding-settings.ht... there are also extensions for vscode that do this, vim plugins, etc
- medwards666 17d agoYeah, this particular bullet point almost made me stop reading the rest of the article thinking that the author has zero idea what the hell they're on about...
- jorisw 17d agoSmart 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.
- pyrale 17d ago> Smart developers don’t write mazes. You don’t choose what your forebears have written, though.
- jorisw 17d agoPatching that up by using comments as a 'map' isn't the right way to deal with that. Refactors and rearchitecture are. Putting in comments just helps procrastinate what's necessary.
- stingraycharles 17d agoRewrites require a lot of effort, significantly more than just adding comments. It’s a pragmatic tool until you actually have the time to do the rewrite.
- jorisw 17d agoI never said rewrites. And the more you put in procrastination-encouraging half-solutions, the worse your code base gets.
- adrianN 17d agoIt's difficult to refactor and rearchitect without first understanding what's there and why.
- jorisw 17d agoAnd yourself putting in comments is the solution to that?
- tromp 17d agoWhen 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 https://tromp.github.io/pearls.html#maze
- ghgr 17d agoVery cool, thanks for sharing! If, like me, you're trying to compile it, don't forget to set the -std=gnu89 flag in gcc, so: gcc -std=gnu89 -w -o maze maze.c Then run it as: echo 10 | ./maze
- wumms 17d agoGot seg fault (gcc 15.2.0 on nixos 26.05) when writing to M[Z] = ... Had to add: char fmt[] = "%d"; and change to: scanf(M=fmt,&C); Works now: char*M,A,Z,E=40,J[40],T[40];main(C){char fmt[]="%d";for(*J=A=scanf(M=fmt,&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,"_.":" |"];}
- monster_truck 17d agoOnce again I am asking, who is this person and why do they think they are qualified to tell me what's best?
- boxesnlines 17d agoHello, I am that person. I have been programming for a long time, but I'm not trying to make any claims that my experience means I know any better. The claim is simply that modern coding practices often produce code that is difficult to navigate and that useful comments and documentation can deliver great benefits. I do make some suggestions on how to approach those things, but they're simply suggestions based on my own experience, I'm not trying to assert any kind of absolute correct approach.
- caporaltito 17d agoTo be honest, this is half of what is posted here. And 99% of the advices you will get in life.
- jdw64 17d agoSounds good. I've lost count of how many mazes I've made. Just call me the Architect of the Labyrinth.
- lintfordpickle 17d agoI 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?
- boxesnlines 17d ago(I am the author) The point of that statement was to run counter to the standards of "always us X type of comments" that some teams adopt. My suggestion is that there isn't a "correct" type of comment that you should always use, but rather that it's highly situational. It's really a parallel to grammar in any other kind of language - there isn't a singular 'correct' way to structure a piece of writing into paragraphs, but it's also typically incorrect to treat each sentence as a paragraph or to avoid paragraphs entirely and write everything as a single block of text. It's unthinkable that a team of writers would ever try to standardise on "never use paragraphs" or "every line is a paragraph", but some programming teams do exactly the equivalent of that!
- lintfordpickle 17d agoThanks for the reply. I didn't mean to be dismissive or discredit the article. The problem you described is real, and one I face daily at work. Anecdotally, every time we've tried to curate the comments and organize them (especially when referencing external documentation, as you also mentioned), it invariably ends up becoming stale and just another point of contention down the road. I'm now more of a proponent of either not commenting, or putting the context and rationale in the commit message instead.
- deadbabe 17d agoYou don’t need maps. You need search. Introducing: ripgrep.
- aktenlage 17d agoI use Ag integrated in the editor all the time. But while it is indispensable for me, I wouldn't say that this helps in all situations, nor is it the best tool to find connections in many situations.