18

After working on projects at work where I had to port/understand someone else?s code and after looking a few open source projects, I've realized most people cannot code. They can get the program to do what they want, but they cannot write maintainable code. They are writing self obfuscating code. They write comments that are useless. So my question is who's writing maintainable code?

32

In theory, everyone who understands the value of maintainable code. In practice, probably only a subset of book authors and software documentation technical writers, since their code will be out in the open and subject to public mockery. (I exaggerate somewhat, because there is good maintainable code out there, but it seems to be so sparse as to seem nonexistent.) It would seem that "in the trenches", it's not easy to expend the effort to clean code. We always intend to clean it up later ? as a professor of mine said: "In the mythical future when all things are possible."

To me, the key is to not rest on one's laurels when code "works". Very few people write clean code on the first try ? it takes multiple passes, thought, and a willingness to change something that works now (possibly breaking it in the process) with an eye towards future benefits. Safety nets like unit tests and version control help make the prospect less scary, but people who are loathe to tinker with code that works will have to accept the fact that they probably won't be writing clean, maintainable code.

For the record, anyone who immediately took umbrage probably has plenty of horrific code themselves, which they'd rather not disclose in public. Besides, unless the OP was referring to your code specifically, being offended makes little sense.

I see this as an interesting question. Programmers tend to shun such questions, since the answers involve a lot of human factors and psychology. I doubt this forum is the best place to find a true answer, but the question itself is thought-provoking...


Edit: Figured I should add a few bonus quotes I (try to) live by:

"Programs must be written for people to read, and only incidentally for machines to execute." (Harold Abelson)

"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." (Martin Fowler)

"Debugging is twice as hard as writing the code in the first place. Therefore, if you [code] as cleverly as possible, you are, by definition, not smart enough to debug it." (Brian Kernighan)

"Always program as if the person who will be maintaining your program is a violent psychopath that knows where you live." (Martin Golding)

12

I was always told how lucky I am to have a project full of great people writing good code. However, I do not think it is about luck. It is responsibility of technical lead to prevent bad code by constantly educating, reviewing and sometimes even replacing people.

If there is a bad code committed in times of no emergency, then something is missing.

  • Add code reviews and make people fix and improve bad code until everyone on the project knows the good from the bad
  • Improve architecture so that simplest solution is the best one
  • Make sure everything is tested, which requires everything to be testable, which improves code
  • Make a team-level presentation about good coding style
  • Write coding guidelines
  • Add cyclomatic complexity (and similar) metrics and act on it
  • Pair junior developers with people that write good code
  • Never ever commit code you do not want other people to learn from and reproduce

Everyone writes bad code from time to time. A lot of the stuff I wrote years ago is bad architecture. However, it is responsibility of developer to evolve, and responsibility of the person in charge of developers to evolve everyone on his project.

Of course, that all works if developers are well motivated. Bad management, small pay or constant emergency (which is also bad management) destroy any incentives to write good code. But maybe then you are working in a wrong place?

9

Clean code is almost nowhere.

Why?

Market forces.

...Because even messy code provides such tremendous value to businesses

Consider going from no computer system to a hacked one... Even this hacked system could multiply your companies productivity.

Now imagine going from a hacked system to a clean system. You save on development costs... but compare that to the original gain from nothing to something. In most cases its a smaller benefit.

Until the market gets completely saturated, and competition demands ever higher standards, and faster turn around, the quality of the average code will remain low.

7

Bad code is a sink for developer resources, skill, morale, and scheduling predictability, and tends to grow, while good code has a tendency to evaporate away or languish comparatively untouched in the presence of bad code.

It takes more effort to fully re-engineer bad code than it does to re-engineer, or take advantage of, good code. This is because while good code is readable, modular, testable, robust, and predictable, bad code is none of those things. The amount of effort it takes to make a change to bad code is significantly higher than for good code. By these dynamics bad code tends to have significant longevity.

Moreover because of the fragility and unpredictability of bad code the most common mechanisms for "fixing" bad code tend to be layering and patching. Meaning hiding bad code behind a giant abstraction layer (and then later hiding that abstraction layer behind yet another, ad infinitum) and making very small changes which tend most often to fix symptoms rather than root causes. These methods themselves just add more bad code and make the system more convoluted, confusing, fragile, and unpredictable, further increasing the cost of changes. The most common result of this process is that bad code grows uncontrollably until working on bad code takes over the majority of development resources, causing the pace of development to slow to a crawl.

This has several deleterious consequences for the development process. First, because so much developer time is spent working with bad code and because, as mentioned above, the average developer responds to working with bad code by writing more bad code the skills of the development team become significantly blunted. Second, because working with bad code becomes the norm people's expectations shift sharply downward. Even if significant parts of the code base are good, people will still have low expectations of what is possible so they'll just count their lucky stars that relatively modest modifications to the good code were faster than expected rather than setting aside significant resources to fully take advantage of the good code. Third, because of the deterioration of developer skill even working with good code will result in the generation of yet more bad code.

This has obvious consequences on morale, because developers tend to spend most of their effort working on horrible code, they don't see their skills improving, and the fruits of their work are relatively minor compared to the great amount of effort that has gone into it. Moreover, bad code is less understandable and less predictable which translates into greater schedule uncertainty and greater stress. Good developers become frustrated by all of this and leave to find greener pastures elsewhere.

(I don't have objective measures of the truthfulness of these positions, these are just my theories based on my experiences in and observations of the industry.)

Note that there are tools and techniques to get out of this mess, some of the best are:

Refactoring by Martin Fowler, Kent Beck, et al

Refactoring cover

and,

Working Effectively With Legacy Code by Michael Feathers

Working Effectively With Legacy Code cover

5

My answer to your question is: No-one.

You probably think that your current code's maintainable, but you know what you had in mind when you did it. Instead, go back to code you wrote 10 years ago. And ask a colleague to explain what your current code does (and how) just by looking at it.

You can probably justify that you were relying on a template from somewhere else in the code, or that the extra functionality needed to get released fast, or the compiler would spit out a minor warning if you wrote it in a more maintainable way, or that it "totally matched the C++ coding standards" (bonus marks when you get the last response when the project's written in Java).

But that's true for everyone else as well.

This is why publishers spend good money employing editors, rather than relying on just having a writer's bible. Because the only real way to decide if the code's fully maintainable is "will the least experienced person who would ever have access to this code understand it".

The equivalent for programmers is Code Reviews, but it's astonishing how often they just become a checklist of "Compiles? Does what it's supposed to do? Seems to match the coding standards templates? Pass. Bracket on the same line as the function? Fail." without any actual consideration of whether the code structure's intelligible or not.

That's not to say that there isn't a section of developers who assume that because "the computer and the end user can care less what the code looks like as long as the code does what it is supposed to do and it does it well", that writing sloppy code isn't a problem.

But they'll learn after a change to dialogue layout that should have taken them 5 minutes + compile takes them 3 days and a complete system re-test.

4

I think a big problem is that reading and maintaining bad code leads to writing bad code. If people don't learn, eg. in universities or during their first jobs, what makes good code, they will not improve. You need some kind of role model. Over time good programmers will learn from experienced team members and develop a better coding style. I other disciplines (medical school, engineering, writing, drawing, ...) students will have to study the work of masters. Why not in programming?

But, yes, there will be a significant number of people who will never learn.

2

My answer to your question is: Everyone.

Writing obfuscating code as you mentioned, does not mean the code is not maintainable does it? Yes it is hard to read and to work with, we all know that because we all maintain or have maintained code like that... which shows that even do it is hard and ugly, it is maintainable.

We, developers tend to believe that writing good code means writing clean, nice code... the computer and the end user can care less what the code looks like as long as the code does what it is supposed to do and it does it well.

2

Very interesting discussion!

Good code takes longer to write. Most projects are under some pressure, most are under great pressure. Net result is that people who want to keep their job write code that gets the job done in the shortest time because most employers do not reward developers for well-written code.

I learned this lesson the hard way many years ago. My code was (at least) much better documented than the other developers and I tested it more thoroughly. However, I was castigated for being "a slow programmer" even though the other developers spent days fixing bugs after "finishing" their code. All that was measured was the initial "commit date" so thoroughness was not rewarded. If the total effort needed to finalize each module had been tracked (including QA's time) I would have been way ahead.

I would guess that developing really readable code adds 25% time to the project compared to what usually happens. Software development being what it is, I don't expect the situation to change much until employers are willing to see that extra cost as an investment -- because they know it will save them money in the future...

As someone suggested above - a strong-willed tech lead with a vision of what's possible is key. Such a person can't succeed without a willingness on the part of the company to support "good dev." Such a combination is still fairly rare...

1

My feeling is that developers are driven to develop code in as short a time as possible: either as a result of a "can do" attitude or just to prove to themselves that they have mastered a particular style. Unfortunately, if the problem they are solving strays off their path of experience then there is a certain amount of casting about to find a solution quickly.

A google here, a quick skim through a technical reference there.

Once some code is turned up that appears to solve the problem it gets copied in and used as the basis for future development. This leads to a slightly different architectural style to the rest of the code, but since that is patchwork anyway one more bit of slap won't be noticed.

And so it goes on until eventually it's a complete ball of mud.

Clearly the way around this is to continuously devote yourself to learning more about your craft. Then go back to that now shameful example of hacky code you shoved in there last week and make it better. By learning about pragmatic programming practices, and taking the crucial step of actually applying them continuously, then slowly that big ball of mud becomes something beautiful.

1

I've realized most people cannot code. They can get the program to do what they want, but they cannot write maintainable code.

There's a logical fallacy here. If they can get the program to do what they want it to do, they can, in fact, code. Just because they don't meet your very subjective standards doesn't mean they can't code.

Clean code (and elegant code) is often overrated, working code is what is most important. Working, performant code is even better. Clean is a distant 3rd to those two. That's why you see so little of it. Getting the code working is what we are paid to do.

There are several reasons why you see what you consider to be unclean code. Think about them before you judge code. First do you know the conditions it was developed under or the requirements they had at the time? Often the code was written before the new fancy methods you think are so nifty were even invented. It had no chance to be clean according to how you personally might judge it. Do you know the scheduled deadline they were under and how hard to meet the deadline it is was and what the consequences for not meeting it were? Do you know how bad the previous code was? Do you know that what you consider to be clean well-written code, you will hate in 10 years and someone else, right now, will think your code is unmaintainable and messy?

Further if you have trouble understanding the code others write, perhaps the problem is you, not the code. Reading other people's code is a skill all developers need to have. No two people solve every problem exactly the same way, you need to be tolerant of other ways of solving problems and learn how to read the code rather than just whine about how awful it is compared to your own.