
Code May Work, But It Still Might Suck - ohjeez
http://blog.smartbear.com/software-quality/bid/276079/your-code-may-work-but-it-still-might-suck
======
RyanZAG
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.

~~~
rtfeldman
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.

~~~
RyanZAG
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).

------
angersock
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...](https://github.com/id-Software/Quake-III-
Arena/tree/master/code)

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...](https://github.com/id-Software/Quake-III-
Arena/blob/master/code/q3_ui/ui_main.c)

Array are for chumps, apparently.

Perhaps my favorite:

[https://github.com/id-Software/Quake-III-
Arena/blob/master/c...](https://github.com/id-Software/Quake-III-
Arena/blob/master/code/q3_ui/ui_atoms.c#L578)

~

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.

------
rilkeanheart
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.

------
dag11
> 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.

------
ryandvm
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.

~~~
Baustin
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.

------
segmondy
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.

~~~
spartango
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.

------
AimHere
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.

------
auggierose
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.

~~~
waterlesscloud
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.

~~~
lttlrck
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>

------
danso
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

------
jfb
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.

------
bajsejohannes
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.

------
tempestn
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.

------
yannickt
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...](http://google-
styleguide.googlecode.com/svn/trunk/cppguide.xml)

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

~~~
jholman
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.

------
rwc
"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?

