Organizing complexity is the most important skill in software development

http://www.johndcook.com/blog/2015/06/18/most-important-skill-in-software/

by speg • 11 years ago

742 276 11 years ago

aspirin• 11 years ago

Organization is the hardest part for me personally in getting better as a developer. How to build a structure that is easy to change and extend. Any tips where to find good books or online sources?

vollmond• 11 years ago

Check out Clean Code by Robert C. Martin. May be helpful.

chiachun• 11 years ago

Structure and Interpretation of Computer Programs. This famous book emphasized controlling complexity and how to build a structure that is easy to extend.

uxcn• 11 years ago

The cost of complexity is exponential -Rob Pike

Toine2• 11 years ago

Same here. I only have 2 years of experience, but right now my opinion is that this is not something you learn in a book (for the moment).

You can learn how to create clean, readable methods and classes with a book (1).

You can learn how to refactor old methods and classes with a book (2).

You can learn how to organize a small team to allow fast iterations with many books.

But building a project lasting more than a few months with constant changes in the requirements, new developers every month, new SDKs and frameworks every 3 days, without the code rotting to death and everything going out of control is a different story, at least for me.

I guess you just learn by watching old guys do what they do after decades of experience...unless someone has a magic book for me?

(1) http://www.amazon.com/Clean-Code-Handbook-Software-Craftsman...

(2) http://www.amazon.com/Refactoring-Improving-Existing-Addison...

Glide• 11 years ago

My personal experience is that I had to maintain a set of applications I wrote for a company. The same application had to be used repeatedly (3-5 times) a year because it supported a specific business processes. It was mundane work, but did it teach me how to organize because it made the pain of disorganized code very real. That one hack comes back to haunt you several times a year.

I was lucky that this was one of the first things I had learned as a developer out of school. It was a little different because the projects were small enough to be solo, but it was humbling because all of the mistakes were my own.

sterlingw• 11 years ago

I just finished a book called "Practical Object Oriented Design in Ruby." It teaches you how to build OO applications that are pleasant to maintain. I highly recommend it.

http://www.amazon.com/Practical-Object-Oriented-Design-Ruby-...

DanielStraight• 11 years ago

The classic essay Big Ball of Mud is relevant as well:

http://www.laputan.org/mud/mud.html

minthd• 11 years ago

> How to build a structure that is easy to change and extend.

This is a very good book on subject, very clear:

http://www.amazon.com/Practical-Object-Oriented-Design-Ruby-...

anton_gogolev• 11 years ago

This can be reduced to:

    Do Not Program Yourself into a Corner

blazespin• 11 years ago

Design patterns by the Gang of Four was great for this.

ebiester• 11 years ago

No. This is an orthogonal concern. This is the equivalent of knowing to use each pattern.

qznc2• 11 years ago

The promise of Design Patterns (tm) is that you can systematically learn to organize your code. The article argues that only experience does.

tempodox4• 11 years ago

Er, isn't design patterns (if you take the buzzwordery away) just a map from “conventional names” to “standard algorithms”?

This article isn't about the choice of an algorithm, it's about organisational aspects. That's something different altogether, and an even larger topic.

sgt101• 11 years ago

Which is why jupyter/ipython is so great -> you can do some fantastic documentation of code with working examples and visualisation, you can do it while you write it !

msandford5• 11 years ago

This is incredibly true. I once turned 60kLoC of classic ASP in VBScript into about 20kLoC of python/django including templates. And added a bunch of features that would have been impossible on the old code-base.

It turned the job from hellish (features were impossible to add) to very nearly boring (there wasn't much to do anymore). So with this newfound freedom I built some machines to automate the data entry and once that got rolling the job got even more boring. Because it was a small company with a very long learning curve the owner didn't let people go, but instead kept them on so that he didn't have to hire and train new people as growth accelerated.

But with all the automation some slack found its way into the system and problems that had normally required me to stop working on my normal job and help put out fires now got handled by people who weren't stretched a little too thin.

Sadly there's (seemingly) no way to interview people for this ability so we're stuck with the standard "write some algorithm on a whiteboard" type problems that are in no way indicative of real world capabilities.

jfoutz4• 11 years ago

"Tell me about writing a compiler"

There's no way to interview for what you're looking for, but compilers seem to require both great organizational skills and some algorithmic chops. there's enough complexity you can't hide lack of one side or the other.

Anyway, asking about building and enhancing a compiler seems like one of the ways to get insight about how people grow code. Every program is a seed. Is this the kind of guy that will end up with a mighty oak tree, or kudzu in 10 years?

pavlov• 11 years ago

In typical software today, much of the complexity arises from interactivity. There are user actions, network events and all sorts of contingencies that make the program flow non-deterministic.

A compiler doesn't have that. It's blissfully old-fashioned, really: read files in, write files out -- no interruptions or real-time requirements. You could do compilers on punch cards.

In a way, the compiler is the most complex piece of software that you could imagine in 1960... But software has moved on and faces a different kind of complexity.

Hence I'm not sure if asking about compiler architecture is really representative of the organizational skills needed by today's software engineering.

qznc2• 11 years ago

Compilers are simple. They are organized as a pipeline. Frontend, middleend, backend. In more detail: lexer, parser, semantic analysis, optimzation 1 to n, instruction selection, scheduling, register allocation, assembly.

Ok, you can do more complex. I work on a compiler, which does it lazily. Transformations are per file and depend on each other. If something goes wrong, you print out the graph to figure out the problem. No idea what the benefits could be. Might actually be a good example, where it could have been simpler.

kazinator2• 11 years ago

Compilers aren't real-time, distributed, multi-user, ... basically anything that is hard from a software engineering perspective which includes deployment and testing. Compilers have reproducible test cases (if they don't, that is a bug in itself). You can catch regressions in a compiler with an automated test suite, and bisect their version history to see where it was introduced. Bug reports from the field tend to be easy to confirm. A compiler isn't going to work well when it has 10,000 users, but mysteriously spiral to a crash when there are 10,100.

Compilers have been developed by lone developers in isolation. Some compilers are only a few thousand lines of code.

Someone who can demonstrate knowledge of making a compiler could well be completely behind in their knowledge about language design. He or she shows how calculations are turned into a tree and then into code on a register machine (i.e. "for-mula tran-slation"). But no idea how to compile exception handling, closures, and doing advanced things with type (beyond just checks) and such.

That is to say, the bar for what can be legitimately called a compiler is quite low.

On the topic of languages, I'd rather interview someone who knows about a lot of modern language features and how they can contribute to the improvement of program organization, yet is foggy about the details of how some of them are might be compiled to machine code.

There is still "compiler worship". On a previous job, I fixed a code generation bug in gcc affecting MIPS targets. Everyone was talking about that: "like wow, he fixed gcc".

odonnellryan4• 11 years ago

I've done a few similar things at my previous employer. Basically, taken it upon myself to write internal reporting applications, to much success. I've also done some other small things (AHK, etc..) which worked out well.

Point is, I've been modestly bringing these up during interviews when asked what I've been doing the past few years. It is always glossed over.

I don't think companies want or recognize that they want someone who will be able to handle these tasks. If they knew these tasks needed to be done, they'd hire for it, right?

Seems some of the most important things that can be done for a company may be hidden to the executive team.

msandford5• 11 years ago

I was fortunate to be a valued player on a small team. But what you're talking about is basically trying to hire yourself in as a tech exec when you're just applying for a job as a programmer. I think that's because management (generally) doesn't really want to hear that they've got a blind spot even if they do.

Ultimately all you can really do is try and work your way into a situation where you have some kind of meaningful equity. Founder, co-founder, early hire, buy a piece of a company, whatever. That's the only way to really get rewarded for your skills; knowing enough about the state of the art to see what can be done better and also having the skills to see those projects through to completion and realizing the benefits thereof.

I wish there was a job title for "good all-arounder with knowledge of the state of the art in a role with substantial self-direction", but I think that's probably "founder" or something. Or "owner of a very small business" maybe?

icbat• 11 years ago

Sadly there's (seemingly) no way to interview people for this ability

In a recent interview, I spent 45 minutes pairing with a current employee. Our goal was to take a (contrived) piece of legacy code, clean it up, and add a new feature to it. I imagine it was a very telling experience for them, and I feel it was more useful than the whiteboarding we'd done before.

Hopefully we as an industry will keep iterating on this sort of interview.

cpursley• 11 years ago

Yeah, a combo of a scanning a candidates github projects and some doing some pairing on real code is much better than whiteboarding.

Balgair• 11 years ago

Yeah, that is cool and lets you get a hand on the job and a feel for what you'd be working on, but it makes me a little wary. Doing work for some employer without getting paid is a red flag. It's not a total klaxon blaring, but it does raise eyebrows.

moron4hire7• 11 years ago

I got fired from a job because I had done this and they couldn't figure out how to keep me billable after that. Well, I got fired because I would "show up late" and "leave early" because there was nothing else for me to do (even though I was actually pulling a full 40 hours, they were expecting 60 out of people).

They could have given me more work, put me on new projects, etc., like I kept asking to be done, but instead they just wanted me to figure out some way to bill the client for 60 hours a week, and not call it "bug fixes" or "new features", because the client wasn't paying for it. That left data entry, which I had automated from a whole day to 10 minutes. They wanted me to go back to entering data by hand.

I would have quit then, but I didn't want to give them the pleasure. A flood had recently destroyed all of my stuff and I used the insurance check to get out of debt rather than replace the lost stuff, so I suddenly didn't need money for a LONG time. It's funny how easily debt can make you a compliant little slave towards people who want you to perform bullshit tasks.

I've been freelancing ever since, making twice what they paid me for only half a week's worth of work. And the flexibility of the freelancing enabled me to pursue a long-distance relationship that eventually lead to marriage. So I say getting fired was the greatest thing that ever happened to me.

msandford5• 11 years ago

I read this story and had a bit of a chuckle. And then I read your username and had a real laugh. Thanks for that!

xacaxulu• 11 years ago

Great takeaway. Debt tends to make 'good little workers'. Stay free my friends!

crdb2• 11 years ago

I've come across this a few times. The managers' thoughts were probably along the lines of "great, I got all my code cleaned up/the hard part of my product built for the expensive rate, now I can fire him and pass on maintenance to the cheap guys over there".

And of course your thoughts were "I'm going to work extra hard initially, which will make a good impression and get the product built on time and all the tasks automated, and then I can coast and it will still be worth their money."

The manager doesn't care because when your code starts rotting due to bad maintenance and badly added features (or just the fact that nobody has bothered taking it over), he'll already have been promoted or changed companies.

wodenokoto• 11 years ago

Billing by the hour is basically just telling people how much effort you expect the task to require smoothed by how valuable it is to you. If you can do it quicker, I say bill the full amount of time and if they have extra inquiries, fit it into the buffer zone.

aswanson• 11 years ago

Awesome, thanks for sharing. Inspirational.

ska2• 11 years ago

Sadly there's (seemingly) no way to interview people for this ability

I think there is. Show the candidate some bad code. Not WTF code, but something you wouldn't be proud of but is realistic. Bonus points if you're comfortable enough to pull this out of your own production system. Ask the candidate about adding some functionality, but be clear that cleanup and refactoring changes are fine (even encouraged). The conversation should be enlightening.

vijayr4• 11 years ago

This happened to me once. I went for an an interview at a huge real estate company. They had a chat with me for exactly five minutes, then gave me a computer (an old one, with keyboard not working properly) and some legacy code. I wasn't asked to fix it, but I was asked to make a small change and given half hour for it. That code had no documentation and no comments. Then 5 more mins to explain what I understood about the codebase - no questions, just me talking about the codebase as much as I understood in that half hour. The whole thing took like 45 mins or so in total. No whiteboard questions etc. And they made an offer.

chiph• 11 years ago

We did something similar at previous job. We handed the candidate some code that was intentionally bad, explained that it was so (so they wouldn't think we wrote like that every day), and then asked what they'd do to improve it. This let us find out a few things - whether they could read & understand someone else's code, whether they could make improvements to existing code, what levels of abstraction they were comfortable working at, and whether they had a strong enough personality to mix with everyone else.

The key was in how we presented it - we didn't want to come across as elitist jerks (but we probably did to some people), so we tried to soft-sell it to them and work it in gradually during the interview.

aaggarwal3• 11 years ago

It would be actually interesting to look at the commits of a candidate's any online project repository from the very start and observe how the candidate made the progress with respect to the structure of code and improvement in coding practice. To check whether the candidate optimizes and refactors the code during the development of the project leading to a stable release.

thirdtruck2• 11 years ago

And then -- and this is important -- actually follow through on allowing and encouraging refactoring, as indicated in the interviews, instead of insisting on "features first, features fast" in practice.

rsuelzer3• 11 years ago

I agree. There are tons of ways to test for this. Write a simple library that doesn't use any good design principles and have your candidate spend some time refactoring it. You can even use the same library multiple times. Heck, have your senior engineers also do this, so that you can get a good baseline for what an ideal candidate should come up with.

FLUX-YOU• 11 years ago

The interview simply doesn't have the time required and both sides will have to be okay with spending more time evaluating each other if we want to move forward.

Also we simply need to teach people the things that we want them to know after we hire them instead of looking for perfect fits.

JohnTHaller2• 11 years ago

Back when I worked corporate I loved when I got time to make the apps I was responsible for better. Getting free time to refactor an outdated procedure written by four different developers who'd all left that just barely worked, albeit slowly, was something I enjoyed. As was getting a couple days for minor bug fixes and small feature adds. I happily had the freedom to sit with the users directly and ask them about how they used the software in their jobs as part of those few bug-fix and feature days for the "late lifecycle" apps (read: they worked OK, so almost zero time was spent updating them other than major crashes and no major versions were scheduled). So, I got to implement unique features based on how they needed to do their jobs that previous developers hadn't thought to add because they'd only done the official 'users get together and ask for features, department head filters it, hands it to our department, department head filters it, assigns it to one of us to do in spare time not working on more important software' thing.

duderific• 11 years ago

That sounds really nice. At my current position, we never get time just to refactor, though supposedly that time is "just around the corner." We are always cranking against tight deadlines. Consequently, we end up with some pretty jacked up code, since as the saying goes "you never get it right the first time."

BurningFrog3• 11 years ago

Sadly there's (seemingly) no way to interview people for this ability

I had one interview where the interviewer simply showed me a printed page of code, and asked me to talk about it.

I spotted a few problems and debatable constructs, and we had a good 3 minutes discussion.

Since at least I spend more time reading code than writing it, that felt like a truer test of my abilities than many of the coding tasks.

PS. Yes, I got the job.

wpietri• 11 years ago

I had an interview recently where we did something similar and it was awesome. They had picked an especially good example: the code was small enough that it didn't take long, but it has a variety of sorts of badness, from coding errors to bad names to bad method grouping to logical errors.

I'm definitely stealing this trick.

HaloZero• 11 years ago

I'm curious, how complex was the code. I would love to try this out at some point. Did it fit all in one page?

fezz• 11 years ago

Agreed, being able to read and reconstruct models from OPC (other peoples code) is such a big piece of coding but hardly ever a part of the interview process.

(OPC also refers to one's own code that when you can't remember wtf you did and the comments aren't useful)

mattLummus• 11 years ago

This is great. Reading (and maintaining, refactoring, improving, etc.) obtuse code is often much more difficult than a fresh slate. Its also a major real world requirement. Where is that statistic on number of engineers doing maintenance vs greenfield development?

baddox• 11 years ago

I think that's a good way to not get false positives, but it seems like something that could yield a lot of false negatives.

anowell• 11 years ago

There's a lot of hate for whiteboard coding. Having been on both sides of whiteboard, code reading, and code pairing interviews, I like them all for different reasons:

Code reading: In <10 minutes, I can have a basic grasp on someone's ability to read, understand, and explain new code. Usually simple examples of <50 LOC in the language of there choice. I've used it a lot in phone screens (just providing URL to the code) and gained the reputation of being able to predict fairly well the quality of a code submission to a "take-home coding challenge".

Whiteboard: in ~15-20 min I can get a grasp on how someone takes a vague problem and works toward a solution and how they are to work with. I'm actually less concerned about code, and more about how they handle ambiguity, flesh out requirements, communicate issues, and think holistically without the distraction of a compiler/syntax-highlighter/etc. I think whiteboarding is slightly more about communication than coding and can provide a lot of context in a short amount of time. Of course, not all whiteboarding interviews are equal - I spent plenty of days complaining about certain whiteboarding interviews, and now I'm clearly biased to believe that mine take the good and leave behind [most of] the bad.

Code pairing. Takes ~1hr to understand and modify some piece of code in a meaninful way. (Maybe there are simpler versions - but in an effort to feel more "realistic", I've always focused on changing a requirement to the candidate's code submission). It's more realistic than whiteboarding, but it carries the [real-world] overhead of getting syntax right, finding docs for a specific function, and other surpries that come up (network issues, desktop crashes, editor problems, etc.). I've seen it work well when there are several interviews that focus on very different skills, but inevitbaly after such interview, I've often felt like I had a very narrow view of a candidate.

s73v3r3• 11 years ago

You could give them some mild spaghetti, and ask how they'd try to improve the code.

I think one reason why what you did doesn't happen more often, though, is because they wouldn't have the freedom to reimplement in a language they felt was more suitable.

msandford5• 11 years ago

Something I just realized that I wanted to write, but didn't, was that I generally don't do well in whiteboard interviews. I've done a few and it's always algorithms that I didn't learn in school because I was EE/CE (not CS) and while I took Data Structures and Algorithms, I didn't take Advanced Data Structures and Algorithms or anything like that. I took two compilers classes (which were great!) and a pile of classes dealing with hardware and the practical realities of computers rather than the theoretical aspects.

I'm pretty happy that I did what I did in school, but I wish that people didn't rely on the whiteboard situation as much. If I can talk about what I did to find the edges and corners of a piece of mail in a picture, and how I used that I can rotate the image to be square and then crop the image so that all you see is the letter and not the background, perhaps my ability to do some kind of whiteboard coding exercise isn't terribly relevant. The odds that I can answer questions about how I developed such an algorithm while still not being able to actually write code are pretty small.

You're hiring me to solve business problems and last I checked FizzBuzz or reversing a singly-linked-list aren't business problems. End Rant.

mattbrewsbytes2• 11 years ago

There is just a nice magical moment though when you grok what an application does and how it is organized, especially when you didn't write it, which is likely the most often case.

I think a large issue is when an application has new people working on it or entirely new teams that maintain it. That is when the original authors methodology and organization of the application falls to the immediate need of the day.

The functionality of the software should speak for itself. Commenting your code with why you are doing something is important to help other maintainers later on, including yourself, understand what you were thinking when it was written.

donatj2• 11 years ago

This. Organization is in the eye of the beholder. I've seen my code bases taken over and completely reversed, and frankly I have done the same. If only there was a better way to communicate exactly what you were trying to do.

mattbrewsbytes2• 11 years ago

I don't know if this is solvable, it could just be human nature.

Some folks like the analogy of software and building construction. I like the comparison to cooking... in this case the closest thing would be how a chef sets up their work space and how it is organized for what they are cooking.

Some like it one way, some like it another - is one way better or worse?

dsr_• 11 years ago

The most important skill in operations: systematic debugging. If the developers did well at organizing, this is much easier.

The most important skill in low-level technical support: diplomacy.

The most important skill in high-level technical support: figuring out what people are actually complaining about.

Note that many low-level technical support problems look like high-level problems, and vice versa.

donatj2• 11 years ago

I find diplomacy a highly important skill as a developer as well. Strangely I feel I've become worse at it as the years go on.

mattmanser• 11 years ago

One of the problems I hit was that I would get really grumpy when particular things were asked for.

Once I learnt to think about why I was getting grumpy, and vocalize the actual problem it was easier.

e.g. A client said to me recently could clicking the blog link open a new window? When I started programming I'd have said "Yes! I can do that!". Then after a few years I'd have got grumpy about it and said something passive aggressive "I guess so. That's not normal though...". Now I think about it, realized I hate it when links on the web behave unexpectedly and that's what's making me grumpy. Then explain to the client that that's you shouldn't take control of other people's browsers on public websites, and the better way is to have a clear link to get back to the shop on the blog.

stinos2• 11 years ago

Not only is it the most important skill (unless for small home projects maybe), it's also the one which takes the longest to learn and hence the one you really improve on during the years and which distinguishes the experienced ones from the lesser experienced ones. Coincidently, it's also the skill for which you won't find a ready-made answer on stackoverflow or any other site/book.

thinking of it, I've also seen this as a typical difference between fresh CS graduates and those who have been programming for 10+ years. The latter would sometime take way longer to come up with clever math-oriented algorythms than the first, because the graduate has been trained for it and still has it fresh in memory, but experienced programmer would make up for that by being able to use the algorithms in all proper 'best practice' ways one can think of. Whereas the graduate would just slam it in somewhere and call it a day even though there are now x more dependencies and whatnot, you get the picture.

collyw4• 11 years ago

This is pretty much how I feel just now (after 12 years). I know Django pretty well after 4 years, and know where and how to add things to avoid breaking other parts of the code and make it work consistently with other parts.

Yet nearly every job I apply for these days wants a 90 minute online test. (I just had to implement a sorting algorithm in psuedo code - I have never in 12 years had to implement a sorting algorithm as I choose an appropriate library to do that for me).

bluedino• 11 years ago

> Yet nearly every job I apply for these days wants a 90 minute online test. (I just had to implement a sorting algorithm in psuedo code - I have never in 12 years had to implement a sorting algorithm as I choose an appropriate library to do that for me).

True, but if you can't implement a simple sorting algorithm how are you going to implement _____ ?

stinos2• 11 years ago

Yup, exactly this. Which is why when we hire, we try to at least get hold of code written by the interviewee and preferrably make him/her come over for a day or so and have him/her do some programming. Much more valueable than 90 minutes of putting someone under some stres-test which doesn't resemble an actual job at all. I read similar things on other comments here so hopefully there's a shift going on. Especially because I would fail terribly at standard interviews as well :]

jaequery2• 11 years ago

Nice post, organization definitely is one of the most overlooked aspects of programming. It takes a lot of experience and thinking to be able to organize properly. It's really what separates the beginner programmers and the experienced ones.

jaequery2• 11 years ago

I think what it boils down to is coding from top down, rather than bottom up. As the OP points out, you need to see the entire landscape.

brightball• 11 years ago

Great read. 100% agree.

justonepost• 11 years ago

Arguably, this is what higher level languages like Java and C++ provide. Tight organizational language metaphors that help implement design patterns in a thoughtful, consistently structured manner.

crusso• 11 years ago

That's kind of like saying that McDonalds provides a healthy meal because they have salads on the menu. The truth is that most people still eat the burgers and fries.

Although higher level languages provide some features for organization, you still must have the discipline and know what you're doing to use them properly.

TickleSteve• 11 years ago

The languages provide the mechanism.... The developer provides the skill needed to produce the organisation.

jeremiep6• 11 years ago

The abstractions provided by Java and C++ aren't very good compared to those provided by, say, Haskell and Clojure.

For the most part, design patterns exist merely to fix the lack of a simpler lambda construct in the language. They more often than not add complexity rather than remove it.

The biggest balls of spaghetti code I've ever seen we're always OOP with design patterns. I've seen far more clean C codebases than Java or C++ ones.

nly• 11 years ago

C++ has lambdas and the standard library is, although baroque, heavily functional and well thought out.

trb8• 11 years ago

I would be hesitant of this so easily accepting this view due to selection bias.

Java and C++ are often found in huge, legacy, or enterprise oriented code bases.

The are plenty of ways to use the abstractions in Java and C++ to write nice code. Just like it is possible to find a Scala or Clojure code base that went crazy with the usage of "cutting edge" features and abstractions in those languages.

And at least with Java, your IDE will always be able to navigate the code effectively.

BerislavLopac• 11 years ago

This pretty much aligns with my take on that from four years ago: http://berislav.lopac.net/post/13061099545/the-most-importan...

As wise men said: All problems in software can be solved with more layers of abstraction, except of the problem of too many layers of abstraction.

jondubois• 11 years ago

I agree that it is an important skill in engineering to recognize when the complexity got too high - At that point you need to take a step back (or several steps back) and find a different path to the solution - Sometimes that means throwing away large amounts of code. It's about acknowledging (and correcting) small mistakes to make sure that they don't pile up into a giant, disastrous one.

Another thing I learned is that dumb, explicit code is highly desirable - It's better to have 10 dumb components to handle 10 different use cases than 1 clever component that can handle all 10 cases.

I think the most important skill is being able to break down problems into their essential parts and then addressing each part individually but without losing track of the big picture.

mmcconnell1618• 11 years ago

I agree. I like to remember that I'm passing code into the future where I might not be working on it anymore. Clear, well named code helps the next developer far more than an obtuse algorithm that smashes all logic into a single line.

JoeAltmaier2• 11 years ago

Almost always this is true. But mature code has been iterated over, and some critical places the code has been optimized out of clarity. Nothing helps then but a document - comments are just not enough to explain the crooked road that lead straight to that solution.

Gracana2• 11 years ago

Another thing I learned is that dumb, explicit code is highly desirable

I knew for a long time that "dumb" code was easier to reason about, but it wasn't until I started looking at compiler output and profiling my code that I realized being "clever" in the source text really didn't matter. Now I'm quite happy to write code in the most straightforward fashion, rather than foolishly "compress" things. I imagine the same experience could be enlightening for a lot of newbie and intermediate programmers.

TillE• 11 years ago

There are definitely exceptions to this (generally correct) rule, in situations where performance does matter. RAM is still incredibly slow compared to the CPU caches, so painstaking cache-optimization can make a huge difference when that's the bottleneck.

Of course, if you're just writing some I/O bound program anyway, it hardly matters.

davidjnelson4• 11 years ago

Agreed. From my experience breaking things down into smaller pieces helps so much with initial development speed, future code change speed, and testability.

bikamonki2• 11 years ago

No part of a system is the most important part, from a car to a huge organization, all parts are equally required to interact and hence make such system 'work'.

Having a clear functional organization at the start (and respect it throughout development) is very important, but after that is equally important to code clean and efficient code, to test, to debug, etc. Then, going up and dow on the solution stack is important to make the right decision on hardware, OS, server, services, etc.

erikb• 11 years ago

Okay, if you need to be so detailed you also have to argue keep in mind that some parts are more important than others. Example with the car: If you leave out the head-rest you might sell your car for a few bucks less or have a harder time to get a customer (low importance), but if you have a car without some kind of motor you don't even have a car (high importance).

While there are many things that are important they all have different priorities, though.

All that said I'm also very sceptical that there is one thing you can learn and then you are a the best programmer. You have to learn thousands of things. And sometimes learning a currently low priority thing now might save you hundreds of hours of pain further down the road. So it's really hard to say what you have to learn.

bikamonki2• 11 years ago

Nope, a car is not a system that was built to be 'sold', it was built to transport people/things safely. If you remove a part of a system and the system still works as intended, it was not part of the system. The head-rest can be removed and the car will still run but with less safety. Hence: all parts of the system are equally required to interact and make the system do what the system should do.

ak39• 11 years ago

Organisational skill is actually an entrepreneurial skill. I'm learning the hard way that there are two diametrically opposing skills you need to master for both running a business and programming effectively:

1. Skills in Creating 2. Skills in Organising those creations

The thing is, the Creating part is always exciting but it's disruptive in nature. The Organising part is boring because it's about taming or tempering the creation in such a way that it can be referenced later on (just like filing your invoices, or timesheets - yuck - but necessary).

Unless you've got a systematic method to organise your creations, you will always be alone with your ideas, find it hard to resume creative chains of efforts and ultimately flounder without profit.

Both in business and in programming.

Damn right it's the most important software development skill.

Toine2• 11 years ago

This is something that I'm learning too, and I'm glad to hear it expressed as simply and clearly as you did, thanks.

We learn it when we're kids : "Clean your room (2) before playing with toys (1)".

Such a basic concept, so hard to scale.

Coincoin• 11 years ago

This is why most of my personal toy projects are coded like a 12 years old with giant functions, god objects everywhere and horrible, horrible, one liners. It's liberating.

This is also why I like game programming that much. A big chunk of the codebase is throwaway code that won't be transported to the next project. When the final deadline comes, you don't feel bad making hundreds of hacks everywhere, and it's fun.

necrodawg2• 11 years ago

So true. If your business is a mess your code will be a mess.

Omnipresent• 11 years ago

On the topic of organization and related to another post about good Software Development books. What are some books that teach code organization as discussed in this post. One I can think of is "Refactoring" by Martin Fowler.

What are some others?

Untit1ed• 11 years ago

For a novice coder I couldn't recommend Head First Design Patterns enough - the gang of four design patterns are a bit controversial these days but the way it steps you through and makes you think twice about how to organise things was really eye-opening for me back in the day.

tempodox4• 11 years ago

I would submit the main point is: You can't learn that from a book but only from experience. The best balance isn't cast in stone but must be found for each problem domain. As much as you can, do your own experiments and experience the consequences of your decisions yourself. Remember that for nontrivial problems, a usual part of the job is learning exactly what problem it is that you have to solve.

davidjnelson4• 11 years ago

Dealing effectively with legacy code:

http://www.amazon.com/Working-Effectively-Legacy-Michael-Fea...

Clean code:

http://www.amazon.com/Clean-Code-Handbook-Software-Craftsman...

markbnj• 11 years ago

It's a very important skill for a programmer to have, especially in the modern environment where distributed systems built from many integrated components are the norm. That said, it's awfully difficult to disentangle the various skills needed for programming and assign an importance to each one, mush less to determine which of them is actually most important of all.

signa11• 11 years ago

there is an excellent book by jon lakos called 'large scale c++ design' which treats organizational or physical design of large scale c++ projects (> 1giga loc). highly recommended.

bmonkey• 11 years ago

I've considered this book a few times, but the following review always stopped me cold: http://www.amazon.com/review/R1ICFUDTH8VXQ5/ref=cm_cr_dp_tit...

Any thoughts on it?

blub• 11 years ago

I would give "API design for C++" by Martin Reddy a shot. The only thing I remember now from the large scale book is to pay attention to compile-time and link-time dependencies, although when I read it I remember that it contained some nice tidbits of info that I had not seen in other books

The big takeaway was that the way the project is split into libraries, files, folders etc and how these map to classes, modules and subsystems matters.

jackreichert• 11 years ago

For those not able the view it. [Cacheview](http://webcache.googleusercontent.com/search?q=cache:http://...)

agounaris• 11 years ago

I would add to the conversation the fact that most projects fail on the set of the initial requirements. In my experience so far I have seen that constantly changing what you want the app to do creates a huge mess in the codebase even if you use latest tool and methodologies.

Looks like there is a great value to organise your app in way to be able to throw away large chunks of code and start over in case there is a big design change.

humbleMouse2• 11 years ago

I like this little article a lot. Personally, I try to write code in a way that reads like a book. Lots of comments, explicit function names, explicit variable names, object names, class names, ect. Talking about languages higher level than C/assembly here obviously.

I am amazed at all the code I see that has terrible/too generic names for functions and variables and objects. Some people get so obsessed over short function names, one character variable names, and complicated looking one liner evaluations.

pinkunicorn• 11 years ago

Totally agree on variable/function names, but for some reason I love complicated one liners. I know its wrong, but its my way of measuring how smart I really am(even though its not).

humbleMouse2• 11 years ago

Much respect to you for acknowledging that it gets your brain off mentally! Need a 12 step program for folks like you. Complicated one-liners anonymous.

bbotond• 11 years ago

The site seems to be down.

Cached version: http://webcache.googleusercontent.com/search?q=cache:Mf9074z...

Djehngo• 11 years ago

mirror (text for the sake of people trying to find this with ctrl+f)

edw519• 11 years ago

the number one most important skill is how to keep a tangle of features from collapsing under the weight of its own complexity

Agreed.

very rarely is there some tricky data structure or algorithm that casts a looming shadow over everything else

Agreed, BUT...

In order to organize, sooner or later, you will have to get clever (with tricky data structures or algorithms).

How I have always built something big and/or complex:

  1. Add lines of code. 
  2. Add lines of code.
  3. Add lines of code.
  4. Holy shit! What have I done?
  5. Refactor.
  6. Combine similar sections.
  7. Genericize with parameter-driven modules.
  8. Still too many lines of code! Optimize Step #7 with something clever.
  9. Go to Step 1.

2 years later: What the hell was this clever parameter-driven multi-nested process for? Why didn't I just code it straight up?

For me, organizing complex code has always been a delicate balance between readibility and cleverness.

Don't remove enough lines of code and it's too much to navigate. Remove too many and it's too much to comprehend.

Organization + Cleverness + Balance = Long Term Maintainability

amelius2• 11 years ago

From [1]:

Nobody is really smart enough to program computers. Fully understanding an average program requires an almost limitless capacity to absorb details and an equal capacity to comprehend them all at the same time. The way you focus your intelligence is more important than how much intelligence you have.
At the 1972 Turing Award lecture, Edsger Dijkstra delivered a paper titled "The Humble Programmer." He argued that most of programming is an attempt to compensate for the strictly limited size of our skulls. The people who are best at programming are the people who realize how small their brains are. They are humble. The people who are the worst at programming are the people who refuse to accept the fact that their brains aren't equal to the task. Their egos keep them from being great programmers. The more you learn to compensate for your small brain, the better a programmer you'll be. The more humble you are, the faster you'll improve.

[1] http://blog.codinghorror.com/why-im-the-best-programmer-in-t...

noir_lord• 11 years ago

I've always described myself as too dumb to write clever code.

I try to imagine that 6 months from now I'll have a critical bug in whatever I'm writing and so I write it for that.

Apropos of nothing, I'd love an editor that could completely hide (not collapse) comments, as when something I write them I don't need them so hiding them would be great but showing them but been able to toggle them on later would be awesome.

vardump• 11 years ago

Clever and magic are very often bad.

In ideal code, functionality and all paths of execution flow should be as visible as possible and easy to reason about.

Unnecessary abstraction should be avoided.

Naming should be consistent and sufficiently descriptive.

jeremiep6• 11 years ago

I find that the older I grow as a programmer the less I enjoy cleverness. There's never a good enough reason to use clever algorithms over boring ones. In fact, most of the refactors I did over the past year was to 'undo' cleverness (thankfully those programmers are no longer working here!)

In terms of performance you sometimes need to do less conventional things, but that's precisely where documenting WHY you're doing it that way is so important.

The small bits of performance you're going to get isn't worth the maintenance hell it's going to cause.

knodi1235• 11 years ago

The small bits of performance you're going to get isn't worth the maintenance hell it's going to cause.

I've always said, that's the difference between programming and developing.

onion2k• 11 years ago

Still too many lines of code!

Being organised has nothing to do with fewer lines of code. A 10 line script can be disorganised and a million LoC app can be well organised. What makes code organised is things not being tangled up together - having well encapsulated logical modules that do one thing (or a set of related things), with a well designed API to get each bit to work with the other bits.

I've found that the more I write testable code the better organised my code gets. Automated testing forces you to design maintainable, organised code - because your test suite really won't cope with disorganised code.

ghthor• 11 years ago

I've found that the more I write testable code the better organised my code gets. Automated testing forces you to design maintainable, organised code - because your test suite really won't cope with disorganised code.

It can, but it will get out of hand really quickly. Worst case scenario the test suite becomes so tightly bound to the implementation that is becomes a part of it. This forces the test suite to be rewritten in the implementation changes, this is the worst case scenario and must be avoided at all costs.

davidjnelson4• 11 years ago

An insight I've had here is to write the code the same way I would have as if I'd done red green refactor tdd, but then add only the essential unit tests at the end. Works very well and is much much faster, but obviously you'd have to have done a lot of red green refactor tdd previously in your career or on side projects to really know what testable code looked like. Reading Working With Legacy Code by Michael Feathers may be a shortcut to that knowledge as well.

setitimer• 11 years ago

Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it. - Brian W. Kernighan

JesperRavn• 11 years ago

There are two kinds of cleverness, and both require balance in their application.

The first is the more obvious kind: exploiting various conditions that occur in your code, in order to come up with a nonstandard solution. E.g. using if (x mod 15 == 0) in fizzbuzz. The problem with this kind of cleverness is that it's hard to understand the code, and it breaks whenever the conditions it relies on stop holding.

The second kind of more subtle. It is where you organize code to properly express the nature of the problem, but this organization is itself conceptually complex. A typical example is using C++ templates where they make logical sense, but they make the code that much harder to read.

The second kind is where balance is needed most. If you use too little cleverness (or maybe too much humility), you end up with spaghetti code, or code where all the organization is done via convention instead of enforced by the compiler. If you use too much cleverness, you end up with code that is hard to read, and brittle, since so many assumptions are embedded in the code.

collyw4• 11 years ago

I always liked Linuses quote about bad programmers worrying about the code and good programers worrying about the data structures. I often find reorganizing my data models can cut down on a lot of code.

tome• 11 years ago

This is why I love Haskell. Haskell seems to increase my ability to manage complexity by one level.

Disclaimer: Haskell is not a silver bullet, not a panacea and I'm only claiming a modest increase, not miracles, but it helps me deal with complexity better than any other language I know.

jdimov9• 11 years ago

I agree that most complexity in software systems comes from managing state. So here is a simple solution - stop doing it. Stop managing state.

Use the right tools for the job. Most mainstream programming languages are ridiculously inadequate for building any production software of any significant complexity without introducing more problems than you are trying to solve.

Use a mature functional programming language that works with immutable data and is designed for building complex industrial systems.

Use a language that was designed from the beginning with the understanding that your software WILL be full of bugs and errors, yet systems must always continue to run.

Use Erlang.

philbarr• 11 years ago

Here we go again with the "functional programming will solve all your problems" thing. It won't. Every language has it's inadequacies.

NovelSpinGames• 11 years ago

Some inadequacies are much bigger than others. The two big ones for me are nulls AKA the billion dollar mistake and mutability by default. I agree that functional programming won't solve all your problems, but it has a lot of very useful features. Some features, like higher order functions, have made their way to more imperative languages. I use higher order functions all the time in my C# programming. And a lot more functional features (or at least F# features), such as tuples, pattern matching, records, and immutable types, are in the C# 7 worklist: https://github.com/dotnet/roslyn/issues/2136

crimsonalucard2• 11 years ago

There's gotta be performance drawbacks to immutable state.

Retra• 11 years ago

How so? You can optimize immutable state into mutable state in most cases where it would be a performance issue.

notNow3• 11 years ago

Here comes the Erlang/FP crusader ...

yessql• 11 years ago

Oh, I thought the most important skill in software development would be SCRUM.

ExpiredLink• 11 years ago

You certainly are a manager, not a developer.

jblow• 11 years ago

It is a reasonable point that organization is important but I have to disagree about "most important".

The most important skill in software development, by far, is managing your own psychology.

scuba7183• 11 years ago

Text only mirror:

http://webcache.googleusercontent.com/search?q=cache:http://...

snarfy2• 11 years ago

There is a term for it. It's called managing scope. I'm surprised the article didn't mention this.

kyberias• 11 years ago

No, that's a totally different thing. The scope (requirements) of the software might be huge but the software could be designed and implemented cleanly and with maintainability in mind. Yet the scope might be tiny and the implementation a mess. This article discusses the skill of taking a mess and turning it into something clean.

snarfy2• 11 years ago

I guess it depends your usage of scope. One is used in defining the problem, the other, the solution. I'm thinking of it's usage when describing the solution.

evandrix• 11 years ago

page not found

shaneofalltrad• 11 years ago

seems we overloaded the server

brazzlemobile• 11 years ago

Here's the Google cache if someone is looking for a mirror: http://webcache.googleusercontent.com/search?q=cache:www.joh...

jimbokun2• 11 years ago

I disagree with the premise that organizing code is not a recognized or appreciated skill among developers.

At least not since this was published:

http://www.amazon.com/Refactoring-Improving-Design-Existing-...

Martin Fowler really struck a chord all the developers trying to do the right thing by cleaning up badly structured code, by giving the practice a name and explaining why it's important. Refactoring is definitely a widely acknowledged and accepted practice today, although probably more so in some communities than others.

knodi1235• 11 years ago

Mirror since the site is currently down:

The most important skill in software development

Posted on 18 June 2015 by John Here’s an insightful paragraph from James Hague’s blog post Organization skills beat algorithmic wizardry:

When it comes to writing code, the number one most important skill is how to keep a tangle of features from collapsing under the weight of its own complexity. I’ve worked on large telecommunications systems, console games, blogging software, a bunch of personal tools, and very rarely is there some tricky data structure or algorithm that casts a looming shadow over everything else. But there’s always lots of state to keep track of, rearranging of values, handling special cases, and carefully working out how all the pieces of a system interact. To a great extent the act of coding is one of organization. Refactoring. Simplifying. Figuring out how to remove extraneous manipulations here and there.

Algorithmic wizardry is easier to teach and easier to blog about than organizational skill, so we teach and blog about it instead. A one-hour class, or a blog post, can showcase a clever algorithm. But how do you present a clever bit of organization? If you jump to the solution, it’s unimpressive. “Here’s something simple I came up with. It may not look like much, but trust me, it was really hard to realize this was all I needed to do.” Or worse, “Here’s a moderately complicated pile of code, but you should have seen how much more complicated it was before. At least now someone stands a shot of understanding it.” Ho hum. I guess you had to be there.

You can’t appreciate a feat of organization until you experience the disorganization. But it’s hard to have the patience to wrap your head around a disorganized mess that you don’t care about. Only if the disorganized mess is your responsibility, something that means more to you than a case study, can you wrap your head around it and appreciate improvements. This means that while you can learn algorithmic wizardry through homework assignments, you’re unlikely to learn organization skills unless you work on a large project you care about, most likely because you’re paid to care about it.

jaytaylor• 11 years ago

Here's an archive.org cache: https://web.archive.org/web/20150622134205/http://www.johndc...

o_nate2• 11 years ago

Or in other words: code should be as simple as possible, but no simpler. I guess you could call it organization or readability or just good design. It requires deeply understanding what you're trying to accomplish and structuring your code to reflect that. I don't think there's any rote, step-by-step procedure that will get you there. Often it is a flash of creative insight that breaks the log-jam and reveals the hidden inner structure of the problem. Once that is revealed the code writes itself. In other words, good code should always make the problem that was solved look easy.

blakeyrat• 11 years ago

Developers understand the word "simple" in different ways.

I personally think of the UI/API: what the code exposes to the outside world should be "simple".

Some people might think about language features. "Simple" is being very selective about what language features you use and what you avoid.

Others might think design patterns, and think the code is "simple" when you can point to any class and immediately recognize what pattern that class implements.

I've come to learn the word "simple" as in KISS (Keep It Simple, Stupid) isn't very useful at all.

o_nate2• 11 years ago

I was thinking of more than the UI/API, although I agree that should be simple as well. I think the internals of the code should be simple, in the sense of being constructed out of simple parts with each part being simply connected to the other parts. This means each method should have a clear purpose and it should accomplish it cleanly without surprising side-effects, and that the flow of method calls should be straightforward.

mathattack2• 11 years ago

This has been my experience too. I've been involved cleaning up a half dozen or so projects that got out of control. In each case, technical complexity was blamed as the reason. After digging in, I found that following commonalities:

- Incomplete, conflicting and misunderstood requirements.

- Lots of "We never thought we would need to do X".

- Poor team communication.

- Mistrust, frequently well earned.

- Harmony valued over truth.

Once these were winnowed away, the problems rarely overwhelmed the technical teams. This isn't to diminish the importance of technical skills. Rather - when everything else is f*cked up, you can't blame the technology or expect a 10xer to pull you out of it.

crpatino• 11 years ago

The advantage of the 10x-er is that he will be reporting directly to a Jr. Executive and therefore cutting ahead of the middle management echo-chamber.

If you genuinely can write code 10x as fast as the average developer, and get feed requirements through a 10x faster channel, that would be the life! I suspect that's where the mythical 100x developer comes from.

mathattack2• 11 years ago

I agree. There are actually two 10x things that can happen - sometimes in one person. One is choosing the right things to do the first time around. The other is doing them very efficiently. When you get a developer who intuitively understands the domain, and programs very quickly, the sky is the limit.

I certainly don't intend to diminish the impact of these 10x developers, just that projects generally get messed up independent of developer quality.

BurningFrog3• 11 years ago

Cleaning up buggy legacy code is a goldmine for learning what not to do.

zackangelo• 11 years ago

Aside from personal discipline and experience, I’ve found that using strongly typed and compiled languages combined with good tools are the best way to accomplish this.

Being able to search for and manipulate symbols at the AST level goes a long way towards eliminating any resistance to refactoring.

grandalf2• 11 years ago

In a recent job I ended up rewriting some of the codebase with this kind of stuff in mind... the results:

- 10% of the LOC as previously

- Code significantly more understandable

- Jr. developer on the team suddenly became a rockstar b/c he could understand what was going on.

notNow3• 11 years ago

Reducing LOC is not always necessarily a good thing. I'd always favor a more readable codebase that takes some effort to explain its purpose than terse one that is vague and obscure that makes your head spin trying to figure out its raison d'etre

grandalf2• 11 years ago

I agree. In this case the code got significantly better organized and more readable in the process.

linkregister• 11 years ago

Google cache, for those experiencing connectivity issues.

http://webcache.googleusercontent.com/search?q=cache:Mf9074z...

Beltiras• 11 years ago

I disagree. Communication is the most important. It's the number one cause of failed software project. Miscommunicated features, capabilities, scope, failure to name a few. My favourite is the last one. Not standing up and recognizing that an approach is not working due to fear has to stand out as a big one.

DevPad• 11 years ago

Yeah, the best developers I've ever seen are about simplifying things, avoid overcomplication for too much "flexibility".

The zen of Python https://www.python.org/dev/peps/pep-0020/ say:

    Simple is better than complex.

petejansson• 11 years ago

Relevant: http://www.safetyresearch.net/blog/articles/toyota-unintende...

Summary: Toyota settled an unintended acceleration lawsuit connected with analysis of the source code for a 2005 Toyota Camry showed it was defective "spaghetti code."

There'a a lot of poorly-organized code in the world, and a typical excuse for not cleaning it up is that "it works" so there would be no return on fixing it. In the Toyota case, the code may have contributed to unintended acceleration, and did result in a legal exposure for which Toyota felt it was necessary to settle a lawsuit.

autotune• 11 years ago

I take it from his site not loading that the most important skill is learning how to scale your site and ensuring it remains accessible during high load times, or using CloudFlare to at least ensure it gets cached.

jtwebman• 11 years ago

The website is down but here is a link from the archive.org site. http://web.archive.org/web/20150622134205/http://www.johndco...

thewarrior• 11 years ago

Yeah this is so true.

I worked on a system where we had to support imperial and metric units. It was done in a pretty bolted on fashion with if statements all over the place. And sometimes it isn't even clear if it could be done in any other way.

Any HN'ers have suggestions on how to do it elegantly.

notNow3• 11 years ago

language?

ljk• 11 years ago

I was thinking that recently. The way I try to stay organized is to comment(with timestamp) every time something is changed so I can refer to it later. Does anyone have more tips on how to stay more organized?

abc_lisper• 11 years ago

This is always a good idea. Here are some of the things I do

- Establish conventions early; Conventions in managing projects, conventions in code. And stick to those conventions. Be predictable, in the code. Use simple names.

- Protect your interfaces. By this I mean, use a central place like a wiki to document your interfaces, so all involved parties may agree upon. Write unit-tests for interfaces. Use libraries like mockito and hamcrest that make it a breeze.(You would lock your home every time you go out, don't you?)

- I mentioned this in the previous bullet, but write tests. Write lots of them, write tests that document any tricky, magical behavior. Cover all the cases(A boat with one hole is bad as one with two holes). Cover all the invariants, any thing that you notice but didn't mention in the source code. Write tests for the bugs you just fixed.

- If you are developing in Java, please use an IDE. I use Intellij, but Eclipse is good too. It makes refactoring code much easier. Rename fields, pull classes up the hierarchy, create abstract classes, create getters and setters automatically with refactoring tools. I am not against emacs or vi, but it is hard to manage Java's sprawl with them.

One of the best programmers I know writes code like it has been generated with a program. It is boring, dull and looks alike in every direction. Every field and method is documented, it says what its purpose is, and why it is needed. He is very fast(fast for a startup, not your average enterprise), accurate and gets a lot of stuff done without magic.

brobdingnagian• 11 years ago

Important according to what metric? Making the software developer feel good, or making the company money? The former is almost certainly true, the latter is almost certainly not.

davidjnelson4• 11 years ago

Avoiding rework can cut costs. Rapid Development by Steve McConnell explains this well.

crimsonalucard2• 11 years ago

Since so many people prioritize getting then task done than writing organized/beautiful code more often then not we get code that isn't organized properly.

Thus, as a result: Interpreting complexity is by far the most important skill in software development. More-so then organizing complexity.

agumonkey• 11 years ago

And Metalevel complexity. I may have been able to craft beautiful code, but I sensed chaos in the way I operate and manages my own resources / tools. I've seen people being organized at many, if not all, layers, solving problem and solving how to help solving problems. Witnessing that makes me feel calm and envious at the same time.

ps: it's also reminiscent of recursion, dogfooding etc.

joshburgess• 11 years ago

"The art of programming is the art of organizing complexity, of mastering multitude and avoiding its bastard chaos as effectively as possible." --Dijkstra

Stratoscope• 11 years ago

Out of all the things I know how to do in programming, reducing complexity is probably the one I'm best at. So how do I get a job doing this? Or a series of lucrative consulting gigs? :-)

I'm pretty sure I'm not as smart as I used to be, and I'm definitely not as smart or productive as some of the younger programmers I've worked with. (Sorry for the ageist remark!)

This may be my secret advantage: I have to keep my code simple enough that even I can understand it.

Here's a fun example that I've seen more than a few times in various forms: four-way navigation, either involving up/down/left/right or north/south/east/west, or both.

In one (somewhat disguised) project it worked like this: the code had several different modules to provide a keyboard interface for geographic navigation, while keeping the geo code separated from the low level details of key codes and events and such.

There was a keyboard manager that mapped keycodes to readable names that were defined in an enum:

  switch( keyCode ) {
      case 37:
          return KEY_LEFT;
      case 38:
          return KEY_UP;
      case 39:
          return KEY_RIGHT;
      case 40:
          return KEY_DOWN;
  }

Then an event manager broadcast navigation messages based on the KEY_xxxx codes:

  switch( keyEnum ) {
      case KEY_LEFT:
          BroadcastMessage( 'keyLeft' );
      case KEY_RIGHT:
          BroadcastMessage( 'keyRight' );
      case KEY_UP:
          BroadcastMessage( 'keyUp' );
      case KEY_DOWN:
          BroadcastMessage( 'keyDown' );
  }

A navigation manager received these messages and called individual navigation functions:

  // Don't forget to reverse the directions here
  events.on( 'keyLeft', function() {
      moveRight();
  });
  events.on( 'keyRight', function() {
      moveLeft();
  });
  events.on( 'keyUp', function() {
      moveDown();
  });
  events.on( 'keyDown', function() {
      moveUp();
  });

These navigation functions panned a map in one compass direction or another:

  function moveUp() {
      map.pan( maps.DIRECTION_NORTH );
  }
  function moveDown() {
      map.pan( maps.DIRECTION_SOUTH );
  }
  function moveLeft() {
      map.pan( maps.DIRECTION_WEST );
  }
  function moveRight() {
      map.pan( maps.DIRECTION_EAST );
  }

Of course most of you reading this can see the problem at a glance: Besides having so many layers of code, how many different names can we give to the same concept? We've got KEY_LEFT, keyLeft, moveLeft, and DIRECTION_WEST that all mean pretty much the same thing!

Imagine if math worked like this: You'd have to have two of every function, one for the positive numbers and another one for negative numbers. And probably four different functions if you are dealing with a complex number!

That of course suggests a solution: use numbers instead of names, +1 for up and -1 for down, ditto for right and left. And pass these numbers on through any of these layers of code so you only need half the functions. If you need to flip directions along the way (like the left arrow key navigating right), just multiply by -1 to reverse it instead of having to make special cases for each direction name.

You might even decide to combine the two axes, so instead of vertical and horizontal, you've got +1 and -1 there too (or 1 and 0, or something that lets you handle both axes with one piece of code). Now you could be down to a quarter of the original code.

Unfortunately, I was brought in on this project near the end to help wrap up a few other tricky problems, and all this navigation code was already set in stone. (And to be fair, working and tested, and who wants to go back and rewrite proven code, even if it is four times the code you need?)

But this would make a pretty good "how would you clean this code up" interview question!

cactusface• 11 years ago

It's actually reasonable. Step 1, translate key push. Step 2, broadcast key message. What you're missing is that there's an alternate Step 1, translate joystick hat push (or mouse drag, or whatever). So Step 2 should be broadcast generic up/down/left/right input message. Step 3, translate message into movement. But what you're missing is that dependent on context, there's going to be other things besides movement that those keys do. Step 4, pan the map with N/S/E/W. Again here, you have the flexibility to work with a rotated map. Your code was probably overdesigned for the use case, but I've seen your solution many times, in books and in real life.

However, I've also solved this problem by passing around polar coordinates, it's elegant and very flexible but you have to munge some data at the beginning. You can also pass around a simple vector [{-1, 0, 1}, {-1, 0, 1}], which is basically what you describe.

d23• 11 years ago

Honestly it seems like the many layers of indirection would be a much bigger problem for complexity. It may not be bad in this situation, but it certainly takes more mental effort to comprehend than seeing a corresponding "right", "down" and "up" for every "left".

wskinner• 11 years ago

“Here’s something simple I came up with. It may not look like much, but trust me, it was really hard to realize this was all I needed to do.”

This reminds me of something Scott Shenker, my computer networking professor at Berkeley, drilled into us every chance he got: Don't manage complexity. Extract simplicity.

Finding complex solutions to complex problems is comparatively easy. Finding simple solutions to complex problems is hard.

thirdtruck2• 11 years ago

Don't manage complexity. Extract simplicity.

I can't second this enough. This is why it's so important to throw away your prototype code, sometimes, instead of trying to fix it. It's also the big value-add of TDD: Well written tests make that extracted simplicity explicit.

userbinator• 11 years ago

I'd say it's not really about "organizing complexity" - because that tends to just push it around somewhere else - but reducing complexity which is most important.

In my experience it has been that designs which look "locally simple" because they have such a high level of abstraction are actually the most complex overall. Such simplicity is deceptive. I think it's this deceptive simplicity which causes people to write a dozen classes with 2-3 methods of 2-3 lines each to do something that should only take a dozen lines of code (this is not that extreme - I've seen and rewritten such things before.)

Perhaps we should be focusing on teaching the techniques for reducing complexity more than hiding it, and that abstraction is more of a necessary evil than something to be applied liberally. From the beginning, programmers should be exposed to simple solutions so they can develop a good estimate of how much code it really takes to solve a problem, as seeing massively overcomplex solutions tends to distort their perspective on this; at the least, if more of them would be asking things like "why do I need to write all this code just to print 'Hello world', and the binary require over a million bytes of memory to run? Isn't that a bit too much?", that would be a good start.

necrodawg2• 11 years ago

This can be hard sometimes. If the business is a mess then your code will be a mess seeing as your code is just a representation of your business.

I work for such a business right now and it's killing me. No amount of high quality code will fix this.

headShrinker• 11 years ago

google cache record: http://webcache.googleusercontent.com/search?q=cache:Mf9074z...

The server seems to be getting hammered.

mkramlich• 11 years ago

I agree that complexity is far up there. But also risk. Also long term thinking. And net cost or net profit. The more years I have under my belt, I think more and more not only about complexity, but also risk, cost, profit. Code and hardware is just a means to an end. Not the end itself.

But yes, seek the minimum amount of complexity to materialize the inherent, necessary complexity. But don't allow a drop of complexity more than that. Architecture astronauts, pattern fashionistas, I'm looking at you. KISS. Spend your complexity dollars where it gives you something you truly need or want. Don't do things Just Because.

bcheung• 11 years ago

I can't load the page, but I would definitely agree with the title.

From my own experience programming here are some the most common and best ways to better organize complexity:

1) Create DSLs. The Sapir-Whorf hypothesis is the theory that an individual's thoughts and actions are determined by the language or languages that individual speaks. By creating DSLs we are able to reason about a problem domain with increased efficiency.

2) Reduce cognitive load by reducing state. By reducing the number of variables in a given section of code we can more easily reason about it. values.map (x) -> x * x is a lot more understandable than newArr = [] ; for (i=0; i<values.length; i++) { newArr.push( values[i] * values[i] ); }

3) Build tools to build tools. The history of computing is one of building tools on top of tools. From assembly language to C to high level languages. What is is the next step? I suspect it is some kind of polyglot environment that is a hodgepodge of languages all working together combined with automated code creation from AI.

ademarre• 11 years ago

Organizing complexity is the most important skill in software development

I agree with this profoundly. Unfortunately, complexity is in the eye of the beholder. When comparing solutions to a problem, different developers will not always agree on which is the least complex.

rsuelzer3• 11 years ago

This times 1000! The really sad thing is that 9.9 out of 10 technical interviews are all about how many Algo's you know. Even if your job will never require actually implementing a single one.

These interviewers do not seem to care at all about the actual process of writing and refactoring code, or what your finished products actually look like.

I know plenty of programmers who can write highly optimized code, but do so in a way where it is completely impossible to maintain.

It's especially heightened when you are given a problem such as "validate if this uses valid brackets, and you have 10 minutes." When under time constraints to solve what is basically an algorithm 99% of programmers are not going write their best code or write code in the way they would normally write code.

If you are using lots of algo's on your programming interviews, I suggest you take a step back and determine if those skills are actually what you want to be testing for in this job. Odds are that it is NOT algo's. Give your interviewer some really sloppy code to refactor into something beautiful. Give them a few hours to work on it, watch how they put the pieces together.

If your position isn't going to require someone to write advanced algorithms on daily basis, testing for them only cuts out a huge swath of potential talent. I also think it probably leads to less diversity in your work place, which is a bad thing.

A Web Developer will never need to solve the towers of Hanoi problem, but they will need to write clean code that can be maintained by others.

</rant>

TrophyWipes• 11 years ago

Interviewee*

And as someone who is about to graduate computer science, your rant makes me hopeful :)

I am much better at refactoring and finding patterns than memorizing algorithms and other things (mainly because they are relatively easy to look up). Do you suggest that I try to strike a specific balance between practicing dealing with complexity, optimizing and making code readable, versus actually trying to memorize and implement certain algorithms for learning's sake?

rsuelzer3• 11 years ago

I'm not a computer science grad, and it puts me at a huge disadvantage simply because I never had any formal training about algorithms. And my day job is to write testable, well-designed production quality code. I don't get to spend a lot of time rewriting algorithms, which as you note, can be easily looked up. The fact is that as a full-stack developer I can count with zero fingers the amount of times I've had to use an self-made algorithm in a production system.

That being said, I do force myself to practice algorithms thru various coding challenges only because I know that this is the specific skill that will land you a job. Which is a shame.

That is not to say that there are not positions that really do require this specific skill, but the vast majority of development positions don't and yet nearly every employer tests their candidates as if their success depends upon their ability to solve an algo in under 5 minutes, instead of their ability to write a good library.

It's a disservice to those of us who do not have CS degrees and have learned to code by spending a great deal of our time writing code.

edpichler• 11 years ago

Our humans are "comparing machines". For this reason we tend to valuate people that solve problems more than the ones who never create them. This is really bad.

Also, in business, if someone is really good administrator, it seems he never does nothing.

varchar• 11 years ago

Interesting. Most comments seem focused on code complexity. In real life situations the complexity is blend of human interactions (attitude, consistency,team,leads, peers, family, emotions) business, market, competition, budget, time, attrition, unexpected events, and more.

Life is complex. Business and workplace dynamics can be complex. People are complex with their own strengths, quirks and situations. Having a broad outlook, developing patience and skills to deal with life and work is part of becoming mature.

AdieuToLogic• 11 years ago

Do the difficult things while they are easy and do the great things while they are small. A journey of a thousand miles must begin with a single step. (source: http://www.brainyquote.com/quotes/quotes/l/laotzu398196.html...)

This applies to systems as much as any thing else it possibly could.

kriro• 11 years ago

"""But there’s always lots of state to keep track of, rearranging of values, handling special cases, and carefully working out how all the pieces of a system interact."""

I'm not a functional programming evangelist but that reads like a very good reason to go for FP. I think a similar point was made in "Functional JavaScript". I don't remember it exactly and it's on my shelf at home but there was some passage about the biggest downside of typical OOP codebases being the mental effort of keeping track of values and value changes.

hamsterdog• 11 years ago

Does anyone know of any book or website or other resource that has before and after examples of good refactoring, or something similar?

Organizing complexity is the most important skill in software development

Related Stories