4 ms·
I feel like this just replaces one vague word "good" with a bunch of other vague words like "readable" and "maintainable". Like of course, maintainable is good
by mcphage 12y ago
I feel like this just replaces one vague word "good" with a bunch of other vague words like "readable" and "maintainable".
Like of course, maintainable is good. But what makes code maintainable? When we're teaching new developers, what do we tell them to do to make their code maintainable? How do we distinguish between code that is maintainable, and code that is not maintainable? That's really the important thing; just knowing it should be "maintainable" doesn't particularly help.
And "readable" is even more complicated. Sure, there are some syntactic things that help readability—consistent indentation and spacing, good variable names, organized files, shorter lines. But beyond that it kinda breaks down. What makes a method readable? Well, probably a small number of lines, few branches, single purpose. That's good. But when you extend that to a codebase, you end up with code that you need to jump between a dozen methods to follow what happens in any given call. Is that readable? Or if you look at it from a class level, having a few methods where the whole chain of logic is in a single place is readable—but then you end up with giant god methods that do way too much. Is that readable? Presumably the balance is somewhere in the middle, but how do we recognize it? Just saying code should be "readable" doesn't really help.
Or "covered by automated tests"—definitely tests are helpful. Except for bad tests, which are harmful, and make fixing bugs or refactoring a painful process. So "covered by tests" can be good, or it can be bad, and adding the wrong tests can make your codebase worse. How do we distinguish between good tests and bad tests?
So I agree that the things mentioned are true about good code, but way too vague to help write better code.
- nathankleyn 12y agoI've always felt that it's a fools errand to define things like that. Certainly things like "readability" are completely community/language centric, it would seem. I wonder if this post presents enough focus for respective communities (both languages and workplaces) to converge on their own definition of these things.
- wjnc 12y agoI think you underestimate the value of culture in code quality (or any operational quality for that matter). More vague words can certainly help, when coupled with a culture where regular discussion of key values is part of operations. So that's still vague: Suppose you have management that says, "We only want and reward 'good code'. And we think 'good code' at least consists of 'readable', 'testable' and 'maintainable' code. The rest, my dear operations, is up to you and your team. And you know what, please a Powerpoint a month about how you measure metrics based upon those vague words. But hey, make the measures durable, and don't try and fool us with 90%+ scores from the get-go." The hope would then be that even 'vague' words can empower the team to measure and improve upon their own interpretation of those words. That could be different from team to team, from company to company. But at least it puts quality in the forefront and that place in the organization where it matters and is measurable / improvable. This is why I also find it a good question for recruiting. People who only want results, but feel all time documenting is time lost, will give answers reflecting that. It might be an OK attitude, even winning in some circumstances, but would not fit in a quality-central culture.
- mironathetin 12y agoWhat about developers experience? Would a 2 year experienced developer ever call a 30 years experienced developers code 'readable', 'maintainble', (add more buzzwords)? Probably not. The older developer may use constructs that the younger has never heard of. If the consequence is, use simple code that everybody can understand, then we never use all of our potential. My hunch is, it is crucial to keep developers and avoid situations where you have to maintain other peoples code as much as possible. Just a quick idea, as I was writing this: Lets compare software with fiction: assume, an author has written a quick draft for a story. It works great, it has more potential, some parts still don't fit in. Would you honestly take the story away from the author and give it to a handful of others to finish it and turn it into a bestseller? It is likely, that you get a mix of styles that gets worse and worse, the more people touch it. Sounds familiar?
- mhomde 12y agoAn author can give a book to different people for proofreading, copyediting, and substantive line Editing. Some of the "voice" of the author might indeed be lost just because good copy editing normally is about 20% of a draft , but it could be argued that what's left is better for it. I agree though that one should try to keep the overall tone/style the same
- mironathetin 12y agoThis procedure is called code review in software development. If done right, it can add great value to code especially, if the author has the last word and we coders develop the gentleness of the best fiction editors.
- deleted 12y ago[deleted]
- malisper 12y agoI guess a good place to start looking for a definition of readable would be Peter Norvig's Rule of English Translation[0]. 1. Start with an English description of algorithm 2. Write the code from the description 3. Translate the code back into English 4. Compare 3 to 1 Code that is easily translated to an English is probably the closest we can get to readable code. As a side note, this entire discussion of what makes good code is making me think of this[1]. [0] https://www.cs.umd.edu/~nau/cmsc421/norvig-lisp-style.pdf https://www.cs.umd.edu/~nau/cmsc421/norvig-lisp-style.pdf [1] https://twitter.com/paulbaumgart/status/571788242174918656 https://twitter.com/paulbaumgart/status/571788242174918656
- AnimalMuppet 12y agoBut, see, "good" is just this word. It's hard to test. "Readable", though, I can test simply by trying to read it. That is, I can test someone else's code by trying to read it. I can't test my own that way; as the author, I'm not qualified to read it for understandability, because I already understand it. So in practice, this boils down to "Read each other's code. If you can't read it, say so. If they tell you they can't read your code, fix it." That is actually fairly simple to put into practice. It doesn't help you get it right the first time, but it shows you where you got it wrong, and tells you how to know when you've fixed it. That's a big step forward from "good".
- mcphage 12y agoWhat that means, though, is you can only determine if code is readable after it's written, and read by other people. And I agree with you. But that also means that, while you're writing code, or thinking about the code you're going to write, or trying to decide between two possibilities, 'readability' doesn't mean anything. So you can't use it to guide you towards more readable code; instead it can merely be used to decide which code should be replaced / refactored / rewritten. And you can't use it to teach new developers how to write better code.
- AnimalMuppet 12y ago> And you can't use it to teach new developers how to write better code. Yes, you can. New dev writes code. It gets code reviewed. New dev gets told: "That's ugly/too complicated/hard to understand. Here's some suggestions for how to re-write it." Over a few years, new dev learns what not to do (which is about the same as developing a sense of taste, or learning a style). It's not something that can be put into a one-hour training class, though...
- analyst74 12y agoIt's harder in practice than you make it out to be. Because our insecurity hinders our ability to say "your code is too complicated for me to understand". Plus, some code is supposed to be more complicated than others, you can't always solve difficult problems with simple solutions. So unless you can understand the code and come up with a simpler solution, just complaining that it's too complicated is not gonna help anyone.