8 ms·

What is good code? A scientific definition

48 points by xomateix 12y ago

nathankleyn 12y ago
Good code is written so that is readable, understandable, covered by automated tests, not over complicated and does well what is intended to do. Couldn't agree more.
- deleted 12y ago
  [deleted]
bnegreve 12y ago
There is this paper [1] by John McCarthy on what he calls Elaboration Tolerance: Elaboration tolerance is the ability to accept changes to a person’s or a computer program’s representation of facts about a subject without having to start all over. This could make a good definition of what is 'good code'. [1] http://jmc.stanford.edu/articles/elaboration/elaboration.pdf http://jmc.stanford.edu/articles/elaboration/elaboration.pdf
codingdave 12y ago
I'm always surprised that "It works." is not #1 on these lists. I get that as developers, it really matters quite a lot whether the code is good. But on a higher business level, software development is a tool, and the most important thing to the business is that it works. Working well and making it better and more efficient are incremental improvements to the business... but code that doesn't work is a deal breaker. Beautiful readable, testable, maintainable code that fails to meet the business need is still a failure.
- nathankleyn 12y ago
  It's on this list as "does well what is intended to do". In fact the article specifically discusses the fact that people, when surveyed, did not mention "it works" as a priority: Works: writing code should always have one purpose, deliver some value to somebody. Writing code that works, that it’s actually deployed somewhere making somebody happy is one of our top priorities. So we were kind of surprised every time a developer didn't include that item in the answer.
- pdpi 12y ago
  It's easier to make Beautiful readable, testable, maintainable code that fails to meet the business need into working code than it is to turn ugly, unreadable, untested, unmaintainable (but working) code to a state where it's not a tragedy waiting to happen. Edit, in a less snarky tone: If beautiful, readable, testable maintainable code is buggy, I'd bet money on the project being structurally sound, but the developer having failed to understand something about the business requirements. It'll likely take a little while to get familiarised with the structure of the code, and then some more time to identify (and fix) the parts of the business logic that are not working as expected. Ugly, unreadable, untested, unmaintainable code that "works" usually doesn't actually work, not really anyhow. It works fine for the cases that make the bulk of day-to-day work, but is almost certainly going to fail horribly when you hit an unusual corner case, and fixing that corner case is going to be a pain, because the lack of structure and testing is going to make it really easy to accidentally break something, and really hard to identify that this has happened (and why).
  - federico3 12y ago
    You are conflating "ugly/unreadable" with "untested" and with "unreliable". There's plenty of horrible but reliable code out there, and vice versa.
    - pdpi 12y ago
      I'm conflating them because, in my experience, they're not independent. There are, of course, plenty of exceptions, but those characteristics tend to go hand-in-hand. It's also often the case that what superficially looks like "ugly reliable code" actually means code that was, at one point, very simple and tidy but has been battle-hardened by years of maintenance. It's ugly because code that implements a lot of complexity tends to look scary as hell. Finally, it's ultimately a truism: truly unreadable code is also code that's hard to modify, and very few systems will go through their lifetime without changes. Even if it works fine today, it'll not meet business requirements tomorrow, and its unmaintainability is a liability.
- practicalpants 12y ago
  I think your point goes without saying, code that actually works is the first thing. But a dimension you've missed... Code that works but isn't readable, testable, maintainable, will end up costing your business dearly. It's a nightmare for any developer working on any task - finding a bug, iterating, new feature, whatever - to have to work with a shitty code base. You could quantify the losses in $ stemming from having to work with shitty code... not only that but you'll have a lot more trouble finding technical help (I'm not alone that I'll ask in an interview "What's your technical debt like?", if the answer is bad, that's probably the end of the interview.)
- brudgers 12y ago
  I guess it depends on the work the code is supposed to do. There's the proximate business problem for which the code provides an answer and then there are all the other business problems which a piece of code might create despite solving the proximate business problem. There's a business case for optimizing on each...and one for everything in between.
j2kun 12y ago
Well is it scientific or pseudo-scientific? In all seriousness, I assume when you ask someone what makes good code, they will assume the code is correct already.
- xomateix 12y ago
  I don't think the post wants to be scientific and stands at the beginning to be pseudo-scientific (actually, aren't all investigations based on methods like surveys or questionnaires pseudo-scientific by definition?). On the other hand it also says: "To be fair, it’s also true that some of the developers had given that for granted (or at least that’s what they said when asked) but it can be symptom of some underlying problem." So it's true that most of the developers asked assumed that the code was correct already but, in my experience, I've also seen in some cases (too many) that some developers believe that they are above everything and they don't worry enough about the value that the code should delivere. I think it's the same symptom as the "throw over the wall" problem. Some developers tend not to worry about anything that is not coding.
- mcphage 12y ago
  Pseudo-scientific, since it offers no way to determine if a piece of code meets their requirements. "Readable", "Maintainable", etc., have no a priori meaning.
mhomde 12y ago
My definition is another: "Great code contains maximum entropy towards to its purpose while being easily understandable and maintainable." Each part is interconnected to ensure quality and efficiency: 1. Maximum entropy means that your codebase should contain as much concentrated "information" as possible in relation to its size. Free of copy & paste code and repetitions that can be reused in libraries, methods and classes. This ensures less code to maintain , easier to spot bugs and easier to spot patterns. 2. Understandability (that includes readable): That means no blob classes or methods with an infinite number of purposes. Each layer of abstraction simple enough to keep in mind in its entirety. 3. Maintainable: It should be bug resistant, making it hard to do the wrong things and easy to do the right (for example putting required parameters into constructors rather than fields or properties). You should be able to replace and/or modify individual parts without side effects. Having as little code as possible also helps with this. I think "covered by automated" tests are nice ... in some cases. It is far from a rule that they're a panacea for every kind of project, code and/or situation nor are all kinds of code wort the effort (models & algorithms: yes, UI: usually no). It also depends on the team and methodology. That good code does what its suppose to do and should be bug free should be a given :)
- MichaelApproved 12y ago
  Is that in order of importance? I'd put readability above everything else. Compact code is nice but I'd rather have self-documenting code, even if it means several more lines of code added to the functions.
  - mhomde 12y ago
    Its hard to put a clear hierarchy of importance since it's a rather fine balance. As you say going for maximum compactness makes it much less understandable (Regex anyone?). That's also why i used the term entropy rather than compactness. It's not primarily the number of characters we're optimizing for but code as information dense and devoid of redundancies as possible. I actually think you should be verbose to the point of building a DSL-like syntax for your solution to improve readability. Even for instance addint small properties and methods that simplifies reading. It's much easier to read if (CanWrite && WillFitDisk) than if (File.Position != File.EOF && Disk.AvailableSpace > Buffer.Size) Even if reusability of those small methods and properties aren't high So I see it as "compact" as possible as long as you fulfill understandability and maintainability.
koja86 12y ago
"Second, because if you write good code chances are that the product you are building will be much better." If "better" means anything related to user experience, adoption or commercial success I think that correlation is about zero. Even the dumbest idea can be implemented by good code.
- nathankleyn 12y ago
  I would have expected better to mean, in this circumstance, less likelihood of there being issues that impact the user - something that almost certainly has a correlation! No amount of "good practice" will protect again an idea being rubbish.
kyled 12y ago
Great code is mostly pure, dense, defines clean interfaces, and favors composition and reuse. Maintenance, testability , readability etc. are just side effects of well written code.
- mcphage 12y ago
  What do you mean by dense?
  - innguest 12y ago
    Dense = "golfed" (in current programming parlance). For instance, Java code is not dense because there's a lot of ceremony, whereas Perl is dense and has little to no ceremony.
  - clebio 12y ago
    Would guess "concise" or "efficient".
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 ago
  I'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 ago
  I 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.
snarfy 12y ago
Good code looks like Carmack's code. http://www.codergears.com/Blog/?p=1313 http://www.codergears.com/Blog/?p=1313
- mattnewport 12y ago
  John Carmack comments at the bottom of that article: "I had almost nothing to do with the PC Oculus SDK — Michael Antanov was the primary architect."
dhimes 12y ago
OT: I need a css style editor that is point-and-click (or copy-and-click) simple. (I currently use Stylish.) I need something that lets me select a paragraph, adjust a style, and it automagically adjusts the class/id style for the page. This light text stuff blows- and unfortunately it kind of biases me against his ability to determine "readabilty" even though that is completely unfair.
fit2rule 12y ago
The only metric that matters: there is a user, using the software.
- rainhacker 12y ago
  That is a very good point. Surprisingly, it didn't even made in top 50. But, I guess the intent here was to capture what developers think is a good code aesthetic, apparently the sample set of the survey do not feel a happy user is one of it.
  - fit2rule 12y ago
    I think that is the most telling aspect of this article: developers are cult unto themselves. The user is, seemingly, secondary to the purpose of writing code in many cases ..
rubicon33 12y ago
I'm not surprised readable is so highly ranked, nor do I disagree that it should be. I am however somewhat surprised that SOLID doesn't have a higher representation. I find that in general, as long as you keep code clarity and readability sacred, you can write testable code by following the SOLID principles. Seems to me it provides the basis of 'good code'.
jacknews 12y ago
Does that company even care? Their team page at https://www.intenthq.com/about-intent/ https://www.intenthq.com/about-intent/ looks like a classic British social class structure; the people-people, so-called "movers and shakers" at the top, the mere techies all scurrying around on the bottom rungs, and QA almost falling off them. Even the office admin is presented above all the technical people. Anyway, negative, small-minded and snide observations aside, here's my totally unscientific summary of their completely scientific survey: Readable Simple (as in not entwined) Functional/Verifiable Maleable/Maintainable Composable/Reusable Efficient But of course all of these aspects are also very subjective.
deleted 12y ago
[deleted]
mikewardle 12y ago
I would define good as Fit for purpose, Maintainable, and id judge this primarily by SOLID Tested, prefferably TDD aor BDD and finally not iver commented, good code should convey what it does without the need for comments, and as code evolves, comments rarely are updated.

48 points by xomateix 12y ago

Good code is written so that is readable, understandable, covered by automated tests, not over complicated and does well what is intended to do. Couldn't agree more.

deleted 12y ago
[deleted]

bnegreve 12y ago

There is this paper [1] by John McCarthy on what he calls Elaboration Tolerance: Elaboration tolerance is the ability to accept changes to a person’s or a computer program’s representation of facts about a subject without having to start all over. This could make a good definition of what is 'good code'. [1] http://jmc.stanford.edu/articles/elaboration/elaboration.pdf http://jmc.stanford.edu/articles/elaboration/elaboration.pdf

codingdave 12y ago

I'm always surprised that "It works." is not #1 on these lists. I get that as developers, it really matters quite a lot whether the code is good. But on a higher business level, software development is a tool, and the most important thing to the business is that it works. Working well and making it better and more efficient are incremental improvements to the business... but code that doesn't work is a deal breaker. Beautiful readable, testable, maintainable code that fails to meet the business need is still a failure.

nathankleyn 12y ago
It's on this list as "does well what is intended to do". In fact the article specifically discusses the fact that people, when surveyed, did not mention "it works" as a priority: Works: writing code should always have one purpose, deliver some value to somebody. Writing code that works, that it’s actually deployed somewhere making somebody happy is one of our top priorities. So we were kind of surprised every time a developer didn't include that item in the answer.
pdpi 12y ago
It's easier to make Beautiful readable, testable, maintainable code that fails to meet the business need into working code than it is to turn ugly, unreadable, untested, unmaintainable (but working) code to a state where it's not a tragedy waiting to happen. Edit, in a less snarky tone: If beautiful, readable, testable maintainable code is buggy, I'd bet money on the project being structurally sound, but the developer having failed to understand something about the business requirements. It'll likely take a little while to get familiarised with the structure of the code, and then some more time to identify (and fix) the parts of the business logic that are not working as expected. Ugly, unreadable, untested, unmaintainable code that "works" usually doesn't actually work, not really anyhow. It works fine for the cases that make the bulk of day-to-day work, but is almost certainly going to fail horribly when you hit an unusual corner case, and fixing that corner case is going to be a pain, because the lack of structure and testing is going to make it really easy to accidentally break something, and really hard to identify that this has happened (and why).
- federico3 12y ago
  You are conflating "ugly/unreadable" with "untested" and with "unreliable". There's plenty of horrible but reliable code out there, and vice versa.
  - pdpi 12y ago
    I'm conflating them because, in my experience, they're not independent. There are, of course, plenty of exceptions, but those characteristics tend to go hand-in-hand. It's also often the case that what superficially looks like "ugly reliable code" actually means code that was, at one point, very simple and tidy but has been battle-hardened by years of maintenance. It's ugly because code that implements a lot of complexity tends to look scary as hell. Finally, it's ultimately a truism: truly unreadable code is also code that's hard to modify, and very few systems will go through their lifetime without changes. Even if it works fine today, it'll not meet business requirements tomorrow, and its unmaintainability is a liability.
practicalpants 12y ago
I think your point goes without saying, code that actually works is the first thing. But a dimension you've missed... Code that works but isn't readable, testable, maintainable, will end up costing your business dearly. It's a nightmare for any developer working on any task - finding a bug, iterating, new feature, whatever - to have to work with a shitty code base. You could quantify the losses in $ stemming from having to work with shitty code... not only that but you'll have a lot more trouble finding technical help (I'm not alone that I'll ask in an interview "What's your technical debt like?", if the answer is bad, that's probably the end of the interview.)
brudgers 12y ago
I guess it depends on the work the code is supposed to do. There's the proximate business problem for which the code provides an answer and then there are all the other business problems which a piece of code might create despite solving the proximate business problem. There's a business case for optimizing on each...and one for everything in between.

j2kun 12y ago

Well is it scientific or pseudo-scientific? In all seriousness, I assume when you ask someone what makes good code, they will assume the code is correct already.

xomateix 12y ago
I don't think the post wants to be scientific and stands at the beginning to be pseudo-scientific (actually, aren't all investigations based on methods like surveys or questionnaires pseudo-scientific by definition?). On the other hand it also says: "To be fair, it’s also true that some of the developers had given that for granted (or at least that’s what they said when asked) but it can be symptom of some underlying problem." So it's true that most of the developers asked assumed that the code was correct already but, in my experience, I've also seen in some cases (too many) that some developers believe that they are above everything and they don't worry enough about the value that the code should delivere. I think it's the same symptom as the "throw over the wall" problem. Some developers tend not to worry about anything that is not coding.
mcphage 12y ago
Pseudo-scientific, since it offers no way to determine if a piece of code meets their requirements. "Readable", "Maintainable", etc., have no a priori meaning.

mhomde 12y ago

My definition is another: "Great code contains maximum entropy towards to its purpose while being easily understandable and maintainable." Each part is interconnected to ensure quality and efficiency: 1. Maximum entropy means that your codebase should contain as much concentrated "information" as possible in relation to its size. Free of copy & paste code and repetitions that can be reused in libraries, methods and classes. This ensures less code to maintain , easier to spot bugs and easier to spot patterns. 2. Understandability (that includes readable): That means no blob classes or methods with an infinite number of purposes. Each layer of abstraction simple enough to keep in mind in its entirety. 3. Maintainable: It should be bug resistant, making it hard to do the wrong things and easy to do the right (for example putting required parameters into constructors rather than fields or properties). You should be able to replace and/or modify individual parts without side effects. Having as little code as possible also helps with this. I think "covered by automated" tests are nice ... in some cases. It is far from a rule that they're a panacea for every kind of project, code and/or situation nor are all kinds of code wort the effort (models & algorithms: yes, UI: usually no). It also depends on the team and methodology. That good code does what its suppose to do and should be bug free should be a given :)

MichaelApproved 12y ago
Is that in order of importance? I'd put readability above everything else. Compact code is nice but I'd rather have self-documenting code, even if it means several more lines of code added to the functions.
- mhomde 12y ago
  Its hard to put a clear hierarchy of importance since it's a rather fine balance. As you say going for maximum compactness makes it much less understandable (Regex anyone?). That's also why i used the term entropy rather than compactness. It's not primarily the number of characters we're optimizing for but code as information dense and devoid of redundancies as possible. I actually think you should be verbose to the point of building a DSL-like syntax for your solution to improve readability. Even for instance addint small properties and methods that simplifies reading. It's much easier to read if (CanWrite && WillFitDisk) than if (File.Position != File.EOF && Disk.AvailableSpace > Buffer.Size) Even if reusability of those small methods and properties aren't high So I see it as "compact" as possible as long as you fulfill understandability and maintainability.

koja86 12y ago

"Second, because if you write good code chances are that the product you are building will be much better." If "better" means anything related to user experience, adoption or commercial success I think that correlation is about zero. Even the dumbest idea can be implemented by good code.

nathankleyn 12y ago
I would have expected better to mean, in this circumstance, less likelihood of there being issues that impact the user - something that almost certainly has a correlation! No amount of "good practice" will protect again an idea being rubbish.

kyled 12y ago

Great code is mostly pure, dense, defines clean interfaces, and favors composition and reuse. Maintenance, testability , readability etc. are just side effects of well written code.

mcphage 12y ago
What do you mean by dense?
- innguest 12y ago
  Dense = "golfed" (in current programming parlance). For instance, Java code is not dense because there's a lot of ceremony, whereas Perl is dense and has little to no ceremony.
- clebio 12y ago
  Would guess "concise" or "efficient".

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 ago
I'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 ago
I 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.

snarfy 12y ago

Good code looks like Carmack's code. http://www.codergears.com/Blog/?p=1313 http://www.codergears.com/Blog/?p=1313

mattnewport 12y ago
John Carmack comments at the bottom of that article: "I had almost nothing to do with the PC Oculus SDK — Michael Antanov was the primary architect."

dhimes 12y ago

OT: I need a css style editor that is point-and-click (or copy-and-click) simple. (I currently use Stylish.) I need something that lets me select a paragraph, adjust a style, and it automagically adjusts the class/id style for the page. This light text stuff blows- and unfortunately it kind of biases me against his ability to determine "readabilty" even though that is completely unfair.

fit2rule 12y ago

The only metric that matters: there is a user, using the software.

rainhacker 12y ago
That is a very good point. Surprisingly, it didn't even made in top 50. But, I guess the intent here was to capture what developers think is a good code aesthetic, apparently the sample set of the survey do not feel a happy user is one of it.
- fit2rule 12y ago
  I think that is the most telling aspect of this article: developers are cult unto themselves. The user is, seemingly, secondary to the purpose of writing code in many cases ..

rubicon33 12y ago

I'm not surprised readable is so highly ranked, nor do I disagree that it should be. I am however somewhat surprised that SOLID doesn't have a higher representation. I find that in general, as long as you keep code clarity and readability sacred, you can write testable code by following the SOLID principles. Seems to me it provides the basis of 'good code'.

jacknews 12y ago

Does that company even care? Their team page at https://www.intenthq.com/about-intent/ https://www.intenthq.com/about-intent/ looks like a classic British social class structure; the people-people, so-called "movers and shakers" at the top, the mere techies all scurrying around on the bottom rungs, and QA almost falling off them. Even the office admin is presented above all the technical people. Anyway, negative, small-minded and snide observations aside, here's my totally unscientific summary of their completely scientific survey: Readable Simple (as in not entwined) Functional/Verifiable Maleable/Maintainable Composable/Reusable Efficient But of course all of these aspects are also very subjective.

deleted 12y ago

[deleted]

mikewardle 12y ago

I would define good as Fit for purpose, Maintainable, and id judge this primarily by SOLID Tested, prefferably TDD aor BDD and finally not iver commented, good code should convey what it does without the need for comments, and as code evolves, comments rarely are updated.