You need to be twice as smart to debug code as you need to be to write it. So if you write the smartest code you can, then you by definition are too dumb to debug it
I hold KISS above most "Enterprise Patterns" with YAGNI as a close second. I think abstractions should be used to reduce complexity with code as opposed to making it harder to reason about. If a pattern increases complexity in understanding, then it should make sense in more cases than not.
I'm also a fan of feature-oriented project structures. I want the unit test file in or next to the code it's testing. For UI projects, similar with React it's about the component or feature not the type of thing. For APIs I will put request handlers with the feature along with models and other abstractions that go together based on what they fulfill, not the type of class they are.
I consider this practice more intuitively discoverable. You go into a directory for "Users" and you will see functionality related to users... this can be profile crud or the endpoint handlers. Security may or may not be a different feature depending on how you grow your app (Users, Roles, Permissions, etc). For that matter, I'd more often rather curate a single app that does what it needs vs. dozens of apps in a singular larger project. I've seen .Net web projects strewn across 60+ applications in two different solutions before. It took literally weeks to do what should take half a day at most.
All for one website/app to get published. WHY?!? I'm not opposed to smaller/micro services where they make sense either. But keep it all as simple as you possibly can. Try to make what you create/use/consume/produce as simple as you can too. Can you easily use/consume/interact with what you make from a system in $NewLanguage without too much headache? I don't like to have to rely on special libraries being available everywhere.
When I was a kid learning programming, I would skim through the whole book teaching Python and type the code using as much keywords as I learned each day, just to boast on my parents and my non-programmers peers about the obfuscated mess that came after.
As I grew I started to contribute to other open-source projects and I came across every kind of unmaitanable spaghetti code, so that I just gave up contribuiting on said project, that is when I gained the consciousness about being zealous on keeping the code as simple as possible so that the next person who comes after me to change the code don't have as much trouble understanding the code, even myself when I revisit the code later.
That altruistic mindset about caring how others read your code, you don't acquire easily unless you get experience how your previous peers did feel.
Writing simple code is also much harder then writing complicated code. If you write some complicated code at the limit of your mental capabilities you can not debug it, but you might also not be smart enough to write the simple code.
I guess this means that one should solve the appropriate problems for a given skill level
My #1 belief about engineering, and one I harp on constantly, is that simplicity is harder than complexity.
I use it as a heuristic. If my work is getting more complex, it's a warning sign that I might be doing something wrong or using the wrong approach. If it's getting simpler it means I might be headed in the right direction.
This is not just about writing code, but designing systems. If you design the smartest (most complex) system you can, you won't be able to debug/fix/extend/maintain it.
Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it?
This is a challenge which I don't think AI tools like Cursor have cracked yet. They're great for laying "fresh pavement" but it's akin to being a project manager contracting the work out.
Even if I use Cursor (or some other equivalent) and review the code I find my mental model of the system is much more lacking. It actually had a net negative on my productivity as it gave me anxiety at going back to the codebase.
If an AI tool could help a user interactively learn the mental model I think that would be a great step in the right direction.
but it's akin to being a project manager contracting the work out.
And that's probably the difference between those who are okay with vibe coding and those who aren't. A leader of a company that doesn't care about code quality (elegant code, good tradeoffs, etc) would never have cared if 10 monkeys outputted the code pre-AI or if 10 robot monkeys outputted the code with AI. It's only a developer, of a certain type, that would care to say "pause" in either of those situations.
Out of principal I would not share or build coding tools for these people. They literally did not care all these years about code quality, and the last thing I want to do is enable them on any level.
Or maybe if you are good at delegating and reviewing code and stepping in to do a deep dive by hand when needed to maintain understanding, then you can use LLMs to greatly increase your speed.
Well, now they can have their way without a pesky developer second-guessing every decision of them.
I don't want to participate on it either, but I'm glad they'll have the chance to make things their way with all the consequences it brings unfiltered.
This is not unique to the age of LLMs. PR reviews are often shallow because the reviewer is not giving the contribution the amount of attention and understanding it deserves.
With LLMs, the volume of code has only gotten larger but those same LLMs can help review the code being written. The current code review agents are surprisingly good at catching errors. Better than most reviewers.
We'll soon get to a point where it's no longer necessary to review code, either by the LLM prompter, or by a second reviewer (the volume of generate code will be too great). Instead, we'll need to create new tools and guardrails to ensure that whatever is written is done in a sustainable way.
> We'll soon get to a point where it's no longer necessary to review code, either by the LLM prompter, or by a second reviewer (the volume of generate code will be too great). Instead, we'll need to create new tools and guardrails to ensure that whatever is written is done in a sustainable way.
The real breakthrough would be finding a way to not even do things that don’t need to be done in the first place.
90% of what management thinks it wants gets discarded/completely upended a few days/weeks/months later anyway, so we should have AI agents that just say “nah, actually you won’t need that” to 90% of our requests.
> We'll soon get to a point where it's no longer necessary to review code, either by the LLM prompter, or by a second reviewer (the volume of generate code will be too great). Instead, we'll need to create new tools and guardrails to ensure that whatever is written is done in a sustainable way.
This seems silly to me. In most cases, the least amount of work you can possibly do is logically describe the process you want and the boundaries, and run that logic over the input data. In other words, coding.
The idea that we should, to avoid coding or reading code, come up with a whole new process to keep generated code on track - would almost certainly take more effort than just getting the logical incantations correct the first time.
One thing to take into account is that PR reviews aren't there for just catching errors in the code. They also ensure that the business logic is correct. For example, you can have code that pass all tests, and look good, but they don't align with the business logic.
I'm not a programmer but I always had the impression that different languages were appropriate for different tasks. My question is, "For what type of programming tasks is English the correct level of abstraction?"
I think the same could be said of anything resembling technical writing. As an example aside from code writing, I think more than half of the machine learning papers out there are horribly written in the sense they rush a point or give no rhyme or reason for certain parts
And the best part, most people shallow read all of them and decide the details are needless till they are forced to deal with the details and then their understanding falls apart in front of them
I have the opposite experience. After years in appsec and pentesting, I can read any codebase and quickly understand its parts, but I wouldn’t be able to write anything of production quality. LLMs speed the comprehension process up for me even further. I guess it comes down to practice, if you practice reading code, you get good at reading code.
Maybe you are used to read high quality code. I suspect that the simple fact that you are auditing some code means that someone actually cares, making it higher quality than average.
High quality code is generally hard to write and easy to read.
reading production code that is known to work can be done with faith and skimming. You don't have to understand every function call because they've each been tested and battle hardened, so it's easy to get an overview of what is happening.
LLM code is NOT like this at all, but it's like a skilled liar writing something that LOOKS plausible, that's what they're trained to do.
People like you do not have the ability to evaluate the LLM output; it's not the same as reading code that was carefully written at ALL. If you think it's the same, that is only evidence that you can't tell the difference between working code and misleading buggy code.
What you've learned to do is read the intent of code. That's fine when it's been written and tested by a person. It's useless when it comes to evaluating LLM slop.
Code is code, it's not a piece of art where we all can have different perspective about what it means or does, so from appsec perspective it doesn't matter who wrote it, just what it does. Also you seem to be interpreting "reading" as one would read a novel, but here "reading" is about finding and exploiting security flaws. So yeah, dunno what you are on about.
Has anyone read The Programmer's Brain and have an opinion about it? I'd like to improve my ability to read and understand code and was thinking about reading it.
I am really bad at reading code to be honest (especially other people's code). Any tips on how I can go about becoming good at this like starting from baby steps?
#1 is easy, #2 requires some investigation, #3 requires studying.
If you're looking at say, banking code - but you know nothing about finance - you may struggle to understand what it's doing. You may want to gain some domain expertise. Being an SME makes reading the related code a heck of a lot easier.
Context comes down to learning the code base. What code calls the part you're looking at? What user actions trigger it? Look at the comments and commit messages - what was the intention? This just takes time and a lot of trawling around, looking for patterns and common elements. User manuals and documentation can also help. This part can't be rushed - it just comes to passing over it again and again and again. If you have access to people very familiar with the code - ask them! They may be able to kick start your intro.
To add to the above; IME, #3 comes first. Study the domain to understand the concepts and their relationships. Read some books/Articles, Watch some Videos, Read Documentation etc. to come up to speed on the terminology/jargon and the general concepts/ideas. Then, in order to understand their mapping to the specific application at hand, sit with the local "guru" (there is always at least one in every group) and pick his/her brain for a few sessions (getting them brown bag lunches works great for this) on the overall architecture of the System. Next sit with testing and use the app as an end-user to understand use-case scenarios which brings all of the above together.
During all the above stages, take copious notes, draw diagrams/graphs/etc. use source code analysis/documentation/browsing/etc. tools eg. doxygen/cscope/opengrok/etc. tools to navigate the codebase and cement understanding. Note also that the above stages are to be done both iteratively and parallelly until you are somewhat comfortable and not necessarily know/understand everything.
With the above in hand, pick one use-case scenario, preferably the most complicated, critical and important one and walk through the code from beginning to end for that path. Remember that you are trying to get the overall picture and hence treat all irrelevant details as blackbox abstractions during initial phases. Over time as you iterate and review the code again and again you can slowly add in the details for a more comprehensive understanding.
Finally, there is no shortcut to the above; it takes time and self-effort. We Humans are natural-born, trial-and-error, continuous-learning problem solvers and so trust to your intelligence and commonsense to find a path to move ahead when stuck at something.
Read code, read code, read code. You will get better.
When looking at a piece of code, keep asking questions like: what does this return, what are the side effects, what can go wrong, what happens if this goes wrong, where do we exit, can this get stuck, where do we close/save/commit this, what's the input, what if the input is wrong/missing, where are we checking if the input is OK, can this number underflow/overflow, etc
All these questions are there to complete the picture, so that instead of function calls and loops, you are looking at the graph of interconnected "things". It will become natural after some time.
It helps if you read the code with some interest, e.g. if you want to find a bug in an open source project that you have never seen the code for.
When you're debugging issues, read the code for the libraries you're using before going to their documentation. It's a great way to get exposed to other people's code.
I find it useful to open the code in an editor and make running notes in the comments about what I think the state should be. As long as the code has good tests you can use debugging statements to confirm your understanding.
As a bonus you can just send that whole block of code - notes and all - to a colleague if you get stuck. They can read through the code and your thoughts and give feedback.
Like everything else, practice. I like to clone repositories of open source tools I use and try to understand how a particular feature is built end to end. I find that reading code aimlessly is not that helpful. Try to read it with a goal in mind. When starting out, pick a tool/application that is very simple and lean on LLMs to explain only the bits you don't understand.
This is positively false. In my anecdotal experience, I have produced code that was brutal to write, but then it was easy to read afterward.
Just like a piece of music being easy to listen to after sweating out the composition.
Sone coding is like solving the puzzle. Once it is written and debugged, you're looking at the solution. The code will readily spoon-feed you the solution again when you revisit it months or years after forgetting everything, possibly even its existence.
Wen code is easy to write but hard to read, you must be writing fluff. Maybe try to steer your career a bit away from that. But do improve your ability to make fluff readable.
Readit News
Just write simple code
I'm also a fan of feature-oriented project structures. I want the unit test file in or next to the code it's testing. For UI projects, similar with React it's about the component or feature not the type of thing. For APIs I will put request handlers with the feature along with models and other abstractions that go together based on what they fulfill, not the type of class they are.
I consider this practice more intuitively discoverable. You go into a directory for "Users" and you will see functionality related to users... this can be profile crud or the endpoint handlers. Security may or may not be a different feature depending on how you grow your app (Users, Roles, Permissions, etc). For that matter, I'd more often rather curate a single app that does what it needs vs. dozens of apps in a singular larger project. I've seen .Net web projects strewn across 60+ applications in two different solutions before. It took literally weeks to do what should take half a day at most.
All for one website/app to get published. WHY?!? I'm not opposed to smaller/micro services where they make sense either. But keep it all as simple as you possibly can. Try to make what you create/use/consume/produce as simple as you can too. Can you easily use/consume/interact with what you make from a system in $NewLanguage without too much headache? I don't like to have to rely on special libraries being available everywhere.
When I was a kid learning programming, I would skim through the whole book teaching Python and type the code using as much keywords as I learned each day, just to boast on my parents and my non-programmers peers about the obfuscated mess that came after.
As I grew I started to contribute to other open-source projects and I came across every kind of unmaitanable spaghetti code, so that I just gave up contribuiting on said project, that is when I gained the consciousness about being zealous on keeping the code as simple as possible so that the next person who comes after me to change the code don't have as much trouble understanding the code, even myself when I revisit the code later.
That altruistic mindset about caring how others read your code, you don't acquire easily unless you get experience how your previous peers did feel.
I guess it’s best to take a look at the code once something works and then see if it can be simplified. A lot of people seem to skip that step.
I guess this means that one should solve the appropriate problems for a given skill level
I use it as a heuristic. If my work is getting more complex, it's a warning sign that I might be doing something wrong or using the wrong approach. If it's getting simpler it means I might be headed in the right direction.
[0] - https://www.laws-of-software.com/laws/kernighan/
Not sure if there is actually data for the assumption to be twice as smart to debug than to write code, but it sounds about right.
And also, if you write the smartest code you can, while you are at your peak, you also won't be able to read it, when you are just a bit tired.
So yes, yes, yes. Just write simple code.
(I also was also initially messed up a bit by teachers filling me up with the idea to aim for clever code)
Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it?
Dead Comment
Even if I use Cursor (or some other equivalent) and review the code I find my mental model of the system is much more lacking. It actually had a net negative on my productivity as it gave me anxiety at going back to the codebase.
If an AI tool could help a user interactively learn the mental model I think that would be a great step in the right direction.
And that's probably the difference between those who are okay with vibe coding and those who aren't. A leader of a company that doesn't care about code quality (elegant code, good tradeoffs, etc) would never have cared if 10 monkeys outputted the code pre-AI or if 10 robot monkeys outputted the code with AI. It's only a developer, of a certain type, that would care to say "pause" in either of those situations.
Out of principal I would not share or build coding tools for these people. They literally did not care all these years about code quality, and the last thing I want to do is enable them on any level.
I don't want to participate on it either, but I'm glad they'll have the chance to make things their way with all the consequences it brings unfiltered.
I've contracted some of this understanding of pieces/intellectual work out to Claude code many, many times successfully.
With LLMs, the volume of code has only gotten larger but those same LLMs can help review the code being written. The current code review agents are surprisingly good at catching errors. Better than most reviewers.
We'll soon get to a point where it's no longer necessary to review code, either by the LLM prompter, or by a second reviewer (the volume of generate code will be too great). Instead, we'll need to create new tools and guardrails to ensure that whatever is written is done in a sustainable way.
The real breakthrough would be finding a way to not even do things that don’t need to be done in the first place.
90% of what management thinks it wants gets discarded/completely upended a few days/weeks/months later anyway, so we should have AI agents that just say “nah, actually you won’t need that” to 90% of our requests.
Deleted Comment
This seems silly to me. In most cases, the least amount of work you can possibly do is logically describe the process you want and the boundaries, and run that logic over the input data. In other words, coding.
The idea that we should, to avoid coding or reading code, come up with a whole new process to keep generated code on track - would almost certainly take more effort than just getting the logical incantations correct the first time.
It’s even worse with offshore devs. They produce a ton of code you have to review every morning.
And the best part, most people shallow read all of them and decide the details are needless till they are forced to deal with the details and then their understanding falls apart in front of them
High quality code is generally hard to write and easy to read.
LLM code is NOT like this at all, but it's like a skilled liar writing something that LOOKS plausible, that's what they're trained to do.
People like you do not have the ability to evaluate the LLM output; it's not the same as reading code that was carefully written at ALL. If you think it's the same, that is only evidence that you can't tell the difference between working code and misleading buggy code.
What you've learned to do is read the intent of code. That's fine when it's been written and tested by a person. It's useless when it comes to evaluating LLM slop.
You're being gaslit.
https://www.manning.com/books/the-programmers-brain
#1 is easy, #2 requires some investigation, #3 requires studying.
If you're looking at say, banking code - but you know nothing about finance - you may struggle to understand what it's doing. You may want to gain some domain expertise. Being an SME makes reading the related code a heck of a lot easier.
Context comes down to learning the code base. What code calls the part you're looking at? What user actions trigger it? Look at the comments and commit messages - what was the intention? This just takes time and a lot of trawling around, looking for patterns and common elements. User manuals and documentation can also help. This part can't be rushed - it just comes to passing over it again and again and again. If you have access to people very familiar with the code - ask them! They may be able to kick start your intro.
#1 will come naturally with time.
To add to the above; IME, #3 comes first. Study the domain to understand the concepts and their relationships. Read some books/Articles, Watch some Videos, Read Documentation etc. to come up to speed on the terminology/jargon and the general concepts/ideas. Then, in order to understand their mapping to the specific application at hand, sit with the local "guru" (there is always at least one in every group) and pick his/her brain for a few sessions (getting them brown bag lunches works great for this) on the overall architecture of the System. Next sit with testing and use the app as an end-user to understand use-case scenarios which brings all of the above together.
During all the above stages, take copious notes, draw diagrams/graphs/etc. use source code analysis/documentation/browsing/etc. tools eg. doxygen/cscope/opengrok/etc. tools to navigate the codebase and cement understanding. Note also that the above stages are to be done both iteratively and parallelly until you are somewhat comfortable and not necessarily know/understand everything.
With the above in hand, pick one use-case scenario, preferably the most complicated, critical and important one and walk through the code from beginning to end for that path. Remember that you are trying to get the overall picture and hence treat all irrelevant details as blackbox abstractions during initial phases. Over time as you iterate and review the code again and again you can slowly add in the details for a more comprehensive understanding.
Finally, there is no shortcut to the above; it takes time and self-effort. We Humans are natural-born, trial-and-error, continuous-learning problem solvers and so trust to your intelligence and commonsense to find a path to move ahead when stuck at something.
When looking at a piece of code, keep asking questions like: what does this return, what are the side effects, what can go wrong, what happens if this goes wrong, where do we exit, can this get stuck, where do we close/save/commit this, what's the input, what if the input is wrong/missing, where are we checking if the input is OK, can this number underflow/overflow, etc
All these questions are there to complete the picture, so that instead of function calls and loops, you are looking at the graph of interconnected "things". It will become natural after some time.
It helps if you read the code with some interest, e.g. if you want to find a bug in an open source project that you have never seen the code for.
Code navigation should be instant and effortless. Get good tooling and train muscle memory for it.
As a bonus you can just send that whole block of code - notes and all - to a colleague if you get stuck. They can read through the code and your thoughts and give feedback.
It's not a joke answer. This entire article is silly. LLMs are great for helping you understanding code.
Especially getting them to generate sequence / flow charts I find is a hack to figure out how everything fits together well.
Claude code is fantastic at quickly tracing through code and building visualisations of how code works together
To get a good mental model, I'll often get an LLM to generate a few mermaid diagrams to help create a mental model of how everything pieces together
Just like a piece of music being easy to listen to after sweating out the composition.
Sone coding is like solving the puzzle. Once it is written and debugged, you're looking at the solution. The code will readily spoon-feed you the solution again when you revisit it months or years after forgetting everything, possibly even its existence.
Wen code is easy to write but hard to read, you must be writing fluff. Maybe try to steer your career a bit away from that. But do improve your ability to make fluff readable.