#stack overflow | Explore Tumblr Posts and Blogs

blubberquark · 7 months

Text

Your Code Is Hard To Read!

This is one of those posts I make not because I think my followers need to hear them, but because I want to link to them from Discord from time to time. If you are a Moderator, Contributor or "Helpfulie" on the PyGame Community Discord, I would welcome your feedback on this one!

"You posted your code and asked a question. We can't answer your question. Your code is hard to read."

Often when we tell people this, they complain that coding guidelines are just aesthetic preferences, and they didn't ask if their code followed coding guidelines. They asked us to fix the bug. That may be so, but the problem remains: If you ask us to fix your code, we can only help you if we can read it.

Furthermore, if there are many unrelated bugs, architectural problems, and hard to understand control flow, the concept of fixing an isolated bug becomes more and more unclear.

In order to fix unreadable code, you could:

eliminate global variables

replace magic numbers with constants

replace magic strings with enumerations

name classes, functions, constants, variables according to consistent coding standards

have functions that do one thing and one thing only like "collision detection" or "collision handling". If your function does two things at the same time, like rendering AND collision detection, then it must be refactored

rewrite deeply nested and indented code to be shallower

rewrite code that keeps a lot of state in local variables into special-case functions

use data structures that make sense

write comments that explain the program, not comments that explain the programming language

delete unneccessary/unreachable code from the question to make it easier to read or from your program to see if the problem persists

My own programs often violate one or more of those rules, especially when they are one-off throwaway scripts, or written during a game jam, or prototypes. I would never try to ask other people for help on my unreadable code. But I am an experienced programmer. I rarely ask for help in an unhelpful way. Almost never ask for help in a way that makes other experienced programmers ask for more code, or less code, or additional context. I post a minimal example, and I usually know what I am doing. If I don't know what I am doing, or if I need suggestions about solving my problem completely differently, I say so.

Beginner programmers are at a disadvantage here. They don't know what good code looks like, they don't know what good software architecture looks like, they don't know how to pare down a thousand lines of code to a minimal example, and if they try to guess which section of code contains the error, they usually guess wrong.

None of this matters. It may be terribly unfair that I know how to ask smart questions, and beginner programmers ask ill-posed questions or post code that is so bad it would be easier and quicker for an experienced programmer to re-write the whole thing. It is often not feasible to imagine what the author might have intended the code to work like and to fix the bugs one by one while keeping the structure intact. This is not a technical skill, this is a communicative and social skill that software engineers must pick up sooner or later: Writing code for other people to read.

If your code is too hard to read, people can't practically help you.

It gets worse. Unreadable code is sometimes unreadable because it is un-salvageable. It is hard to understand because there is nothing to understand, it would not work, and you need to go back to the drawing board.

Defensive Responses

This is not where the problem ends. Often, after a couple of rounds of back and forth, after questions like "Well, you say there is a bug, but can you tell me what you would want the code to do in the first place?", or "Is this a class or an instance? If it's supposed to be an instance variable, could you give it a lowercase name?" or "Could you give that variable _obj a more descriptive name? It looks like you are assigning different things to this variable in different parts of your loop. Perhaps you could use two variables with different, more descriptive names", you see a defensive response. The original question asker is not interested in making code easy to read, just in making it work. As I explained above, this is a confused way of thinking, because ill-posed questions and unreadable code make it difficult to impossible to make the code work, or to even understand what making it work would look like.

"Style is irrelevant." – This is by far the most common one. Since coding style, comments, variable names, and even re-factoring code into smaller functions do not affect the output, and thus not the correctness of the program.

"I asked for help with bugs, not style." – This is a variation on the first one. As long as there is no concrete and discrete bug, style feedback and questions for clarification can be discarded.

"This is too much work." – The original poster explains that making the code more readable is too much work for them, and fixing the bugs would be easier for others.

"Nobody will see the code anyway" – Nobody will see the code of the finished product, so it's irrelevant. Sometimes there are variations like "We aren't graded on code quality, only correctness" or "This is for a class project, nobody will depend on the code, so we don't need robustness."

"This is just throwaway code, it doesn't have to be good." – Like the previous one, this is frustrating to read because somebody posted the code on a forum for other people to read and asked them to understand it, and then said he doesn't care if it's readable or debuggable.

"I asked you for help." / "I am asking the questions here." – The original poster refuses to answer questions, because he asked, he expects answers, not questions in return.

"Don't blame me, I didn't write it" – We have completely left the realm of correctness and style now. The poster knows the code is unreadable, or doesn't make sense. He tried to protect his reputation. But he doesn't like the tone of the responses. Its not his fault the code doesn't make sense. It's not his fault if it doesn't work. Common variations are "This must be correct, it was the accepted answer on StackOverflow", or "I copied this from a tutorial", or "Don't blame me, this was written by GitHub Copilot". Often part of the problem is that the code has different parts written in different styles, or uses different data structures in different places, and both parts could benefit from a re-write to make them more consistent with each other. At other times the problem is that the code from the book is "correct" for certain purposes from the book, but not really suited for the problem at hand.

"I apologised already" – The poster is frustrated because he said "I am sorry I am a n00b" or "I am sorry for my bad English" already. Then somebody said his code is unreadable or his prose makes no sense. The poster sees readable code, or at least code that is readable enough to understand what the idea was, as a courtesy, as a social custom, not as something necessary to make the whole question and answer thing work. The same goes for a firm grasp of English. The poster apologised already that his English is bad, and you should just see past it. Dealing with this is especially difficult, because Q&A is framed as some kind of status game, and the poster is trying hard to save face already. Push-back will make him feel like he is losing face, and he will only get more defensive.

Causes

So where does the problem begin? Why do people write unreadable code, post it online, and get defensive? I think the answer is a combination of programming skill, social skill, and simplistic mental models.

Software Engineering is Difficult: Obviously, one root cause is that beginner programmers can't already write readable code from the start. Writing readable, well-factored code that is easy to debug, re-use, and adapt is something that comes with experience. Writing code for other people to read can only be learned after one has learned to write code.

Magical Thinking/Limited Cognitive Empathy: The most common and most direct cause of this phenomenon – the refusal to help others read your unreadable code – is not the unreadable code itself. It is the belief that it should be easy for experienced programmers to understand the structure of and intent behind a piece of code, even if the person who wrote it didn't. If you see software as basically magic, and don't see computers as soulless automatons that do what they do because they are built that way, then this is an easy trap to fall into. A variant of this works for language. If somebody is bad at English, or bad at the technical jargon needed to ask his question, he will often think that the question he thought up in his native Klingon was perfectly well-formed, and that other people should have no trouble reading his words, because they also think in Klingon, so they would translate it into a question that makes sense anyway.

Status-Consciousness: Many beginner programmers feel the desperate need to distinguish themselves from other beginners, and if they have been learning JavaScript for two moths now, they want to be seen as real programmers, not as children who play with Scratch and build Redstone contraptions in MineCraft. They want to be taken seriously. This reminds me of a five year old boy who stretches out his arm and tells me he is THIS BIG, and he is already FIVE, going on SIX, and he will go to SCHOOL soon.

Naive Mental Model of De-Bugging: Every program has a certain number of discrete features bugs, and when you remove all bugs, you end up with a program that works. This is of course nonsense. You can write a program that has an indeterminate number of bugs, or a program that implements an algorithm that doesn't quite work, or a useless program, or a program that does random nonsense.

With any luck, sooner or later, programmers will learn the technical side, and the social and collaborative side of software development.

#programming #python #forum culture #stack overflow #teaching programming

78 notes · View notes