Hacker News Reader

I think you can check off everything on this list and still write inscrutable code. The worst code I've seen is code that was written so that only one person understands what's happening -- the author. Typically the code has too many branches and ridiculous call stacks. The writing analog is a run-on sentence.

This usually happens when the programmer at fault is really smart but still hasn't learned that at some point in the future, someone needs to come along and understand the code he/she wrote.

Maybe we need editors?

What you think code reviewing is for?

Totally agree that more code reviews are needed. I guess then the question becomes, how do you teach someone to do a good code review. Code reviews come from experience I get it, so if you are a junior programmer then you get your code reviewed by someone senior. But there is also one very important part to a code review. It being able to give good advice to someone. Not to be over critical but to provide help that is actually going to build someone up. At a company I use to work at, they did this beautifully.

1) Every check in required a code review by a peer. In your commit statement, you specify who reviewed your code.

2) If a senior programmer wrote code for a feature that wasn't too complex he would get a code review from a junior programmer. The junior programmer doing the code review, learned what good code looks likes and second learned how to give feedback in a constructive manner as he was talking to someone with more experience than him/her.

No, traditional code reviewing is just spot checking. That is analogous to having an editor only look at a few passages of a novel. An editor needs to work with the whole text. This is the trouble with formal code reviews. Pair programming attempts to solve this by making all code get reviewed as it gets written. Like it or hate it, that at least tries to solve the core problem.

I suppose we're not "traditional" in this sense, but at Facebook we do somewhat more in-depth code reviews than just spot checking. Generally if you're modifying an existing system, you get one or two people who're familiar with that system (and thus know the big picture of code design, layout, etc) to review your diff.

If you're writing something totally new, you usually throw ideas and mocks (either UI or code-structure) until you decide on a solution that works.

I've found this to be pretty good at helping newer engineers write good (and idiomatic) code without hindering development speed much.

Code review might serve the same purpose (depending on how you do it) but I've had a hard time getting organizations to "buy in" to code reviews for various reasons (fear, pride, cost, etc.).

On the other hand having the Architect act as editor after the code is written not only provides the "code review" function, but it provides the additional benefit of providing the Architect with feedback on the original design, and how the abstract design ideas are translated during the construction phase.

I think it would improve communication on both sides (Architect and programmer) as well as overall quality...very nice...

Titling people editors, the ones that are senior in an organization and might be titled as architects or senior engineers, now, would be incredible. With their current titles they are involved much more at the beginning of the process than at the end, when 'editor' implies the opposite.

It would be nice to have the senior folk guide the developer as opposed to handing off a blueprint and getting out of the way. (Not that its like that everywhere, just some places I've been)

Agreed. And here is an example where, without comment scores, it is impossible to know how many other people feel the same way.

The best approach — with or without upvotes — would be to ask people if you want that information. Upvotes wouldn't reliably provide it — I and many others feel the best use of the voting system is to promote insightful and thought-provoking comments even if I don't believe they're ultimately THE right answer, and we vote accordingly.

I'm not sure why that is relevant here. We're not voting on anything, just discussing it.

Besides, you could always send a message to the author and ask if you're interested.

This is the linux model. First, discussion then front-line coders create a patch, then lieutenants review the patch and submit to their superiors who review the patch and ultimately, all patches go through Linus before being committed to kernel. This way, the style and potential issues are enforced by the most senior people that are the stewards for the code base.

Linus has deputized a few people to commit without his review, I believe.. but this is after years of working with them.

If you don't work in the code you shouldn't get an opinion and giving one to someone like that is asking for trouble. At the end of the day, it will be a developer who feels the pain, not the architect. There really is no incentive to do a professional job if it doesn't make your life harder later (sometimes that isn't even true).

*professional means good quality balanced with maintenance and time available during development.

Just putting this out there, besides the undoubtedly negative sentiment it will bring. Try pairing. You don't have to do it all the time, but if you are working on something that you have to think about, bring another developer over. The best way to ensure what you are writing is good is to get another set of eyes on it. Preferable a set that will actually need to do something with the code at some point.

No, it is a run on paragraph. The equivalent of a run on sentence is a method that is way too long.

Also, we practice code review at our work. That is definitely a way of fulfilling the role of being editors.

I've taken the editor role in a couple of recent contract jobs. While the clients were both complimentary, I think I didn't do too well for one of them, where I came in to an existing codebase with a shortage of domain knowledge -- and this is going to be a general problem for a specialist editor, more so than with prose. I was more like a copyeditor. (For the other client I'd written the code they started with.)

This problem is hard to solve.

It is not in the interest of the programmer to allow others to understand his code. That would make him easily replaceable. I know quite a few consultants who write like that on purpose and secure their jobs this way.

Programmers are also not rewarded for clean code. They are rewarded for quickly delivered code. Beautiful code that is delivered two weeks too late is usually a bad idea. This is business logic.

It is easy to measure, how long it takes a programmer to develop code. It is much harder to measure, how much time is wasted to maintain badly written code.

Much speaks against writing clean code, little is in favour. The only persons interested in this are later maintainers and academics.

Lets face it: whats wrong with code that is a bit messy but does its job correct and quick? If the author himself has to edit it and does not understand it anymore, then he/she will refactor. If there is no need to touch this code because it does its job, who cares? If the original author is already gone and there was no time to make someone else familiar with his code and style, think about how people are treated in your company and refactor management instead of code.

All of those are absolutely true, and many of them reduce to one thing

    - didn't have a frickin' clue what the code was supposed to do

I remember reading the old cartoon (and it was already old when I saw it 25 years ago) of the manager saying "You guys start writing code, I'll go find out what they want", and swearing I would never be that kind of manager only to find, all those years later, that many of my programmers had already internalized the notion and routinely sat down to write code without having a clear idea of what the block of code was supposed to accomplish.

You say that on a site where the ethos is "start building a company and product now, we'll figure out what it should do later" - because that's a way that works.

I think the ethos here is clearly different than you suggest. Trying to build a product without having an idea what it should do is not a way that works.

Being open to refining your idea or pivoting as you go is a horse of a different color.

But trying to write code without a clear purpose in mind is the equivalent of monkeys banging away at typewriters, to return to our "writing" metaphor.

37 Signals in their book rework put it really well. You have a business model from day 1. Not everyone is Facebook and Twitter so having a concept of a business model is very important. So yes, having a clear vision of your product is necessary. That vision can change while you are building but you still need to have a starting point.

meh. i work at a small shop. most of the code i see that sucks was written by competent programmers under high schedule pressure. the code is clearly not well understood anymore, but if you trace the history you can see it's due to a few years of tacking on features as quickly as possible. the technical debt surely slows us down sometimes, but hey that was a business decision, maybe even a correct one! core business functionality is rock solid, its mostly UI code that sucks.

I wonder what the average startup codebase looks like?

I get tired of the "blame the shitty programmers" line of thought. We're all shitty programmers. Yet we all "understand variable scope" and "what the code was supposed to do." Some of us have such a large ego that we think it's others. No, Sancho. It's you.

Code gets complex as hell very quickly. If it was building a house, it would be built in a week and architected on the fly. The person mixing the concrete, who has to know the concrete grade and drying time, also has to know that the upstairs has just shifted and now the load is too much on the center beam.

The reality is that, unless your dealing with tiny apps, that "bad programmer"? It's you.

I've seen applications with fairly large scope that have clean code.

For the most part the Django codebase has clean code, and its rapidly understandable. Where that's not true is the original SQL db, and the Forms library. Elsewhere its a dream to hack with.

I'd also praise the codebase of SQLite, and Lighttpd---these two are very clean.

good low level backend stuff takes years of iteration under static business requirements. its also a well-understood domain with many prior implementations to learn from, and the 'companies' tend to be product-based so you have much less customer pressure.

teams reacting to changing or poorly-understood requirements (think enterprise and defense software contracts) have a much harder task. nobody has solved the problem before, nobody understands the problem, and project managagement is typically forced into waterfall in order to make sales, so its not like there's time to redo things that get duct-taped together, if the duct-tape holds.

I agree that we are too slow to point the blame at ourselves. It's healthy to be self-critical.

That said, there are programmers who are legitimately lacking both in basic skills and desire to attain those skills. It's orthogonal to the problem you're talking about, but these people do exist, and they're not as uncommon as one might hope. I can teach the difference between pointers and references; I can't teach you to care.

This. I have ascended to a managerial position a couple of years ago, rising from the ranks to steer what used to by a group of my peers. A lot of cruft had been ailing the team for years, but one guy stood out: he had been fired, rehired and now acted as if there was nothing he could do to damage his standing in the team. When we were peers, it bothered me; when I became his boss, I really tried to sway his attention into the product, into learning, into becoming more than a "drag this out of the component box" programmer.

Needless to say, it failed. The guy was irreparably lazy, and trying to get him excited about building the things we are fortunate enough to get paid to build only made him try to put me under a bus when he got the chance. I had to let him go, and have slept better ever since.

That's SENIOR Sancho to you, bub. :-p

The worst code I've seen is from programmers who had no mental model of what they were doing, just changed things at random until tests passed.

The worst writing I've seen:

* is ungrammatical to the point of incoherency

* loses its train of thought mid-sentence and talks about something unrelated

* is full of irrelevant details

* simply ignores everything above the sentence level, producing mere text, no argument, story or whatever it was supposed to be

Not really the same failure modes.

Not really the same failure modes.

Really? Because except for the first one (which we have compilers to thank for), your three remaining points apply equally well to a lot of code I've seen.

Even if you are working in a compiled language, you still can't always rely on the compiler. The compiler will not stop a programmer from writing invalid code, without any tests, and checking it into a repository, where it silently waits for an unsuspecting programmer to discover it months later....

"How do I do what I want here? Aha, someone already wrote ExactlyWhatIWantHere.... WTF, it doesn't even compile? But how is anyone using it? Oh, it's not being used anywhere? How the heck did it get here? Ugh..."

The first point applies as well, to when his counterexample has happened.

Who has not seen a piece of code that is so bad they don't even understand how it can compile, coming out of a newbie?

Doing strange undefined things in C comes to mind as a usual case where this happens.

The only tickybox that matters is the last one: if that is ticked, there's no hope for it but to put up Dilbert around your work space and sing sad songs while you work.

I think that the point of original post is precisely that many do know and understand all the things you listed, but for some reason fail to apply them on the job.