Code May Work, But It Still Might Suck | Hacker News Reader

Code May Work, But It Still Might Suck

blog.smartbear.com

45 pointsohjeez33 comments

There has recently been a huge uptake on 'make code beautiful' all over the place. The main thing the beauty seems to emphasize is variable naming and other inane surface level driftwood.

This stuff is not what makes code beautiful and any code can be converted to look like this with simple formatting tools. Judging code on being 'good' or 'bad' based off whether someone hastily dumped it through a neatness format tool is a terrible precedent.

Code is beautiful if

  1) Accomplishes the goal it has to perform in an
     easily understandable format.
  2) Is designed in a way that modifying one part of
     the code will have minimal/no impact on other parts
  3) Is named well enough ('self documenting') so that
     the amount of comments can be kept to a minimum
  4) Hides as much boiler plate code inside helper
     functions/libraries as possible so that the real 
     logic is not lost in a sea of boiler plate.
  5) Is specific enough that 'tricks' are not required
     to use it for the intended purpose.
  6) Uses generalized code in common areas - and has
     this generalized code moved to external libraries
     for maintenance and re-use across projects.

And very importantly (but often missed in this case):

  Uses system knowledge to optimize code to run as well
  as (within an order of magnitude) the most performant
  possible code for that problem can run.

Systems can be as beautiful as they want, but if your OS takes 15 minutes to boot or your FPS game runs at 2 fps (and as people are beginning to notice: your web app server can only handle 50 users), all of your beautiful code is wasted and should be thrown out.

This post by Ole Lensmar perfectly aligns with your idea of "beautiful" software: http://blog.smartbear.com/software-quality/bid/275689/What-M...

The biggest problem with professional programmers entering the field is in my opinion precisely the lack of ability to reason about how given code meets the criteria you mentioned and how different versions of the code score using those criteria. Many people have a very hard time at all explaining why they choose to do something one way over another. You have to work on a single project for a long enough time to be able to see how your decisions from one year earlier affect the current code base to learn to do this well.

I could not agree with #5 any more. I can't tell you how many times I see default parameters being set incorrectly (i.e. defaults to a corner case so you have to set it on every call). It creates code that looks like:

foo( $data, FALSE, FALSE, FALSE, TRUE );

That drives me nuts.

That code example completely breaks rules #1, #2, and #3 completely. There are probably a lot of ways to refactor that code so that it's still specific. The most common method is to define constants for each value and then pass them in as 'flags' to the method. For example:

  foo( $data, Foo.NEVER_USE_CATS | Foo.DRAW_SQUIGGLIES );

This pattern lets you add in new parameters easily and makes it very clear what parameters are being passed to any function and set sane defaults. This style is widely used in Android to good effect.

For the most part, this is a good list.

However, the addendum about performance optimization is (A) not even directly related to code beauty, let alone a requirement for it, (B) a goal that tends to, in practice, come with a price tag of uglier code, and most importantly (C) a call-to-arms for premature optimization.

The paragraph at the very end is a good example of when you should optimize for performance: when parts of your code base are unacceptably slow. It's the impact on user experience that's the problem, not something intrinsic to the beauty of the code.

The idea that your code cannot be beautiful unless you use system knowledge to optimize it "within an order of magnitude [of] the most performant possible code", before you even know there is a noticeable performance problem with it, is bad advice.

Indeed - the last part about performance is the complete opposite of typical code beauty - it's why I listed it separately yet still called it very important when considering code beauty. I disagree that it is bad advice - I have seen code that matches the first 6 standard points yet was bad code because it performed terribly. Simply making pretty and understandable code is not good enough if it's actively harming the users of the system.

The key issue here is that you can have code that does perform within an order of magnitude that still fully follows the first 6 points. I'd argue that this code is inherently more beautiful than code that completely throws performance out the window - it is grounded in the reality of the physical universe.

For example, pretty code that loops through a large array multiple times when it could be changed to loop only once is, in my opinion, fairly 'ugly'. It's throwing out the user's experience (he might have to wait 0.1 of a second more on that button press - annoying!) for slightly easier to read code.

Obviously this is a line in the sand and you could argue either way, but whenever discussing code beauty I always bring up performance as they are often two sides to a coin and both are important. I agree with you that throwing out code beauty and optimizing everything is very bad - but you need a balance here. 'We will fix it later when performance becomes a problem' nearly always ends up as 'We will rewrite the performance critical parts of the code - customers are complaining!' - and now all of your pretty code is lost.

EDIT: Slow performance is also one of the prime indicators of code quality that a user can see. If code performs poorly, a user is likely to perceive that code as being badly written (and I think he is correct). Perception is reality, and when that user is deciding between two systems, he will be biased towards the faster one as he now believes that system to be of higher quality (even though the code on that system is a buggy mess that he just hasn't tripped yet).

> The idea that your code cannot be beautiful unless you use system knowledge to optimize it "within an order of magnitude [of] the most performant possible code", before you even know there is a noticeable performance problem with it, is bad advice.

I disagree, but the key phrase here is "within an order of magnitude." I don't think it refers to squeezing out CPU cycles but rather to choosing the right general solution.

Using a cursor in sql when you don't need to is ugly programming whether or not the specific module has a real-world performance problem or not. Similarly, looping multiple times through a singly-linked-list when a hashset was called for is ugly code as well, regardless if that particular method has a significant real-world effect on performance.

I'm not sure we really disagree here except on semantics. Choosing the right data structure or language idiom for the job at hand isn't premature optimization, at least not the kind that should be avoided, and it's essential to beautiful code IMO.

I'd summarize this way: Code Might Suck, But It Still Works (better than your beautiful unlaunched stealth project).

Beautiful code works, and everything else is refactoring.

a comment on items 4 and 6: whilst I totally agree with it, from my experience, many programmers decide in advance what might be used in a more generic sense, and end up generalizing code that is effectively used once or twice. This means in some cases that instead of reading one function to understand what's going on, you have to jump through several files to understand the whole thing...

My personal rule of thumb is that if some pattern repeats 3 times or more, I would consider it boilerplate, and refactor it into a separate library/function. Before that, it's not enough to make a 'rule' out of one or two occurrences.

Very much agree with this. It seems like a sort of analysis paralysis that specifically affects some programmers. Reminds me of a HN post a while back actually by someone who was passionate about building games, but ended up generalizing into building game engine tools, then graphical tools, etc., eventually spending years building ever more general tools, without making any real progress toward his true goal.

You can write your code with modularity in mind, without necessarily having to completely decouple and generalize everything. Once it becomes sufficiently beneficial for a particular module, the refactoring then shouldn't be too onerous.

(Regardless, this 'beautiful code checklist' is fantastic.)

It doesn't make code beautiful to run (nearly) as performant as possible. These are two different things.

So, citing the id codebase is not the greatest idea here. Consider Quake 3 (possibly one the most widely-abused codebases for games in the world):

https://github.com/id-Software/Quake-III-Arena/tree/master/c...

Their codebase has smart things implemented smartly, dumb things implemented smartly, smart things implemented dumbly, and dumb things implemented dumbly. To wit:

https://github.com/id-Software/Quake-III-Arena/blob/master/c...

Array are for chumps, apparently.

Perhaps my favorite:

https://github.com/id-Software/Quake-III-Arena/blob/master/c...

And Q3 is still probably one of the best codebases I've worked with, in terms of learning clever tricks and being hackable.

"Beauty" is such a shitty metric for how good code is--I think you want to maximize the things implemented smartly, and minimize the dumb things.

Some of the best engineering in the Q3 codebase was unseen stuff used for the virtual machine the whole thing ran on--itself having roots back to the VM in Quake 1.

While I agree with most of what has been written, I think it's necessary to point out one of my key tenets with software development: code (good or bad) must earn the right to be improved (i.e., optimized, de-suckified, etc.).

For an entrepreneur this means that 99.9% of the sucky code written should stay that way...because no one will ever use it. Write something that "works" and then see how and how much it is used before going on to optimize.

It's not a binary question of sucks vs. doesn't suck. It is a question of how much of an issue the suckiness is creating. I'll spend 100X the time trying to improve beautifully written code that is taking up the largest chunk of CPU time rather than focus on a function that is rarely used but makes me throw up in my mouth when I see it.

> Coding habits are a reflection of the person

I completely disagree. I've seen cases of friends starting out programming and not indenting a single line, to having beautiful, consistent, and readable code now. They just had to learn and gain experience.

As a user of SoapUI, I find it amusing that SmartBear is writing posts on sucky code. SoapUI for the Mac may very well have the worst user interface that was ever created. It somehow manages to make the GIMP UI seem fluid and well designed.

If you don't mind my asking, what version of SoapUI are you using? I'm not going to say that everything was fixed and all better after SoapUI 4.5, but the team did manage to fix some of the issues that we've been having on Mac.

That said, we know that our Mac version of SoapUI is still pretty rough (we actually have a blog post from a while of back referring to SoapUI 4.5 as the "suck less on Mac version"). The reason for this is partly because Apple is doing its damndest to break Java on the Mac. But we've also needed to work on improving the Windows version, since that is what most of our users use. In all honesty, the reason we even have a Mac-version of SoapUI is because that team has a childish love for all things Mac.

We do have great hopes for the long-term: The new Product owner for SoapUI, Matti, is a Mac guy, our Technology Director, Henrik, for the SoapUI team only uses Mac, and the SoapUI Scrum Master, Ulrika, is a Mac fanatic – hopefully this all pays off.

So, please bear with us; we're working on some other projects that will delay any work on the Mac. We're re-building our entire build and release process in order to be able to release tested and validated versions of SoapUI more frequently. Boring stuff, but the advantages are huge. We’re really hoping we'll be seeing improvements for the Mac over the next year.

Fortunately or perhaps unfortunately UI and code are two different things. I agree with you that they have horrible UI design. I would also say that once you got past the UI it worked flawlessly, so perhaps the internals are better than the box they came in.

There are beautiful codes that have never made a dime.

There are ugly codes that have made hundreds of millions if not billions.

I rather ugly/sucky code that makes money over beautiful code that doesn't. I've grown to love money making ugly code.

I'm not sure how much you would love maintaining it though.

This comes to a question of values. Do you build things because you want money? or do you build things because you enjoy the beautiful end product?

These two are not mutually exclusive, and neither is superior to the other in a vacuum. Obviously, if you are running a business, then you must value the money. If you hope to make your users and fellow engineers happy, you probably should value the beauty.

How much each drives your decisions is ultimately subjective and personal.

The author claims that doom3 is beautiful because it has minimal comments.

Doom3 is heavily commented as evidenced by both Fabian Sangard's review (linked to in the article) and by examining the code itself(also linked).

I know it's the internet, but the very least people can do is read whatever it is they cite before offering factual statements on it.

Yeah, I stopped reading that article when I read that sloppy people produce sloppy code. The thing is I can be pretty sloppy in life, but I can also be producing code that is beautiful on a level that 99.9% of so called "programmers" don't understand.

Yeah, that's one of the most ridiculous statements ever made about programmers.

It's hard to imagine how someone could know more than a handful of programmers and say such a thing.

Quite. It reminds me of my old boss: tidy desk, tidy mind.

Uh huh. More like tidy desk, nothing better to do. And BTW have you seen Einsteins desk?

http://kottke.org/10/04/einsteins-desk

Here's one thing that I've learned recently that I wish had been ingrained into me at the beginning:

You will spend far, far more time reading your own code than writing it.

If you come into coding with that perspective, then good design and habits is something that is logical to prioritize, not merely something that comes from being OCD.

We all grow up learning to write in such a way that we experience writing as something much more time consuming than reading. This is a mindset that has to change when what you're writing is code

All software sucks. All of it. Even the software I love. All we can do is try to leave the campsite slightly less polluted than you found it.

Something I learned from the game industry is that sucky code can be the best code. Coming from the university and a company that treasured beautiful code, it was hard to get used to.

I find that it's pretty similar to premature optimization. First you make it work. Then you ship it. If you constantly keep coming back to that code and find it difficult to work with, then you make it beautiful and modular.

Some caveats:

* You need a small team and a small code base, so at least one person near you knows how it's working.

* Projects need to be time-limited. Ugly code will be much harder to read when you forgot how it worked. If the project is done and over with within a year, then it's fine.

* Everyone on the team needs to agree that it's possible to work this way. Some people just freak out when code isn't beautiful. I got over it, but I'm not sure everyone can or want to.

* One of the reasons we write beautiful code is that it's just simpler to write. It's a way to structure thoughts. In those cases, you should of course do that. It takes a while recognizing when to write ugly code.

Reminds me of my grade 10 computer science teacher. This was in 1996, coding in qbasic iirc. Anyway, he was biiiiig on comments. Consistently the only marks lost on my submissions were for insufficient comments. But these grade 10 assignments were pretty simplistic. I mean, if the assignment is to print the numbers 1 to 10 on the screen, wtf are you supposed to comment? I eventually got a perfect score by inline commenting every fucking line of the program.

Glad to see the article make the distinction between well written, well commented code, and over-commented code. Not once through high school or university was I taught the basic concept of 'comment the why'; the what should be self-explanatory.

FTA: "Kennedy said guides are common, but not to the clear and explicit length Carmack went in his guide, and that makes the difference."

In my experience, this is not uncommon, especially with C++ codebases. I've seen quite a few style guides that go in at least as much detail as Carmack's guide. Two publicly available guides that come to mind are the Google[1] and Webkit[2] style guides.

Maybe it's just me, but I don't find the Doom 3 code style that exemplary or exceptional.

[1] http://google-styleguide.googlecode.com/svn/trunk/cppguide.x...

[2] http://www.webkit.org/coding/coding-style.html

I agree that the style guide they link is pretty short and leaves a lot out. Although there were a few nice bits, I think.

The really laughable bit in the article was "One of the reasons the Doom code is so readable is because ... Carmack set up a Coding Style document". Oh god, if only this was all it took.

Actually, pretty near the entire article is a joke to anyone who's written more than 100 lines of professional code, and I'm astonished it's getting upvotes on HN.

Also, why would anyone take seriously the opinions of professional educators on this? I happen to agree with all of their comments, but, unless they have maintenance experience, they are precisely the people least qualified to speak on this subject. Maybe get those quotes from tech leads or engineering managers at respected corporations that hire interns, that would mean something.

"In his revealing biography of Steve Jobs, Walter Issacson told of Jobs's fastidiousness when it came to product details, even the stuff people would not see. Jobs demanded the unseen features be as finished and polished as the visible."

How does this square with the apparent abysmal state of affairs for developers working with iCloud sync?

Reply on news.ycombinator.com