Software Engineering Stack Exchange is a question and answer site for professionals, academics, and students working within the systems development life cycle. It only takes a minute to sign up.
Sign up to join this community
There is a problem with the way I code. Regardless of how much of a plan I write beforehand, the code becomes overcomplicated quickly.
Reading books on good practice and attempting to adhere to their principles isn't working.
Is there some surefire/proven way of auditing code to simplify it, other than being more thorough and dedicated in the planning stage?
There are indeed techniques for gradually simplifying code and improving design by doing so. The general technique is known as "refactoring". Note that this term is used both informally (to mean "anything that changes how code is designed without changing what it does") and formally (to mean "following a specific refactoring discipline"). I am referring to the latter definition here.
In particular, this problem has been much studied by Martin Fowler, and his book "Refactoring: Improving the design of existing code" is one of the classic books of software engineering, and is well worth reading in this area.
The general technique that the book suggests is:
1) Write very detailed tests for the section of code you intend to refactor.
2) Make a specific SMALL change to the code. For example, inline a method, rename a class, extract some code into a new method, extract a superclass from an existing class, etc. (Fowler has detailed lists of many such small transformations in his book, along with suggestions on how/when to do them. Most of the names of existing "automatic refactoring" features such as those in Eclipse, IntelliJ, etc. were taken from those used in his book. Essentially, these are like "design patterns" but are used for modifying existing code rather than for designing it in the first place.)
3) Re-run your tests, to verify that you haven't broken anything yet.
4) Repeat until you are satisfied with the results.
Thus, large changes to the code can be made by accumulating multiple small changes, with testing between each change.
Obviously, if you are in the habit of writing and retaining detailed tests for your code in the first place (a unit test suite, regression test suite, etc.), the above process will be much easier than if you have to write the tests immediately before you start refactoring. Also, it will be much easier to do this if the part of your test suite that you are re-running between each change is capable of running quite quickly.
Note that refactoring code in this way is a DISCIPLINE. It is not the same as simply randomly going around changing code. The frequent testing during the process is essential for ensuring that any inadvertent changes that you make to the program's behavior are quickly caught, while you can still remember what you did. For this reason, it is also often a good idea to do refactoring separately from other development which adds or changes the behavior of the program, since those sorts of changes are likely to invalidate existing tests. You could, for instance, alternate phases: Add a feature, then refactor a bit, then add another feature, then refactor some more, then fix a bug, then refactor, etc.
If you are consistent in programming using these techniques to simplify your code, the overall trend of your code over time will be that it gradually becomes simpler and easier to read, rather than the reverse (which is, sadly, more common in industry).
You may also find that some of the community around the Agile and/or XP software development methodologies may be helpful as to how/when/what to refactor, since continuous refactoring in this manner is considered a required feature of many such methodologies.
I have seen many projects gradually become so crufty and complicated that nobody understood them and they eventually had to be discarded, because maintaining them eventually took more effort than rewriting them would. Refactoring is a way to avoid this problem.
Practice.
No, really.
You will never fully appreciate a technique in a book or blog post until you've written your first plate of spaghetti or big ball of mud, and realize that many of these techniques are just effective ways to tame that complexity. Then you will understand them at a deeper level, much deeper than the cargo cultist who is just stringing patterns together to look cool, but doesn't fully understand the reasons behind them.
Check out the patterns. Are any of them easy? Well, they're definitely easier than writing a plate of spaghetti or a big ball of mud, and having to maintain it later. But you still have to make a study of these patterns. Even the best painter uses more than one brush.
My one surefire way is:
Not being afraid to refactor the plan at the first hint that the code is turning complex.
(Which, of course, does not negate at all what you have already mentioned about being more thorough and dedicated in the planning stage.)
Post your code to Code Review, and let someone else simplify it for you. ☺
In seriousness, if you study the simplifications recommended among the thousands of Code Review answers, you'll find that the range of techniques is far too broad to summarize in an answer. Just off the top of my head, I can think of:
itertools and list comprehensions.)Basically, as @RobertHarvey says, Practice. But now I've given you a resource where you can take advantage of other programmers' experience.
public and protected members a library should expose; the fact that an author might find the library's own API adequate doesn't mean that consumers won't have...
The easiest way is to get yourself a mentor who writes clean code, show him or her your messy code, and ask what's wrong with it.
The thing to realize is clean code doesn't happen at the planning stage, and you can't continually "adhere" to clean coding principles. You can only periodically reset to them. You will write messy code. As soon as you recognize it, you fix it. The more frequently you reset your code, the better it will be.
You said you've read books on the principles, so you know what they are. You can be methodical about resetting to them. It's often helpful to take a principle to extremes before backing off. Like tuning an instrument, it's easier to hear the proper set point if you first go way past it. If your function is way too long, split it into the smallest possible pieces, then recombine a little perhaps.
....no. There is not.
I never really thought before of the idea of such a thing existing because it's relatively obvious there's no perfect solution, but now that you mention it....that would be awesome!
However no, there is not nor will there ever be a perfect solution to ensuring your code isn't terrible, quickly, slowly, or inbetween (sluickly?).
If at all possible, use an IDE supplied with (at least) these two components:
Books are great to understand the why and the how - you need a tool that will pitilessly ferret out the what and the how much.
You can then check periodically the code you wrote, and wherever e.g. the cyclomatic complexity of a function exceeds a predetermined threshold, you refactor the function. And so on. Put aside some time in each development cycle and devote it to refactoring; that's a possible "when". With time and practice you'll be able both to better estimate the refactoring overhead, and reduce said overhead by fixing most things almost automatically as you go by. Also, you'll be able to see what metrics (and values thereof) work best for you.
(Finally, "overhead" is a mistaken label - think of it as "small and comfortable down payments that allow your code not to go into huge technical debt, and bankrupt the project at some time in the future").
In my experience, if a software developer doesn't properly understand the system/domain he is writing the code for then the code is quite likely to become over-complicated.
The reason for this is fairly obvious. Simple code has a structure that mirrors the problem being solved or the domain being modelled. That way the code's behaviour tends to emerge from the structure, rather than being encoded as a large number of explicit cases.
Another way to spot this error is when you need a large number of test cases to check that the code is working properly and you discover failures in all sorts of edge cases. If the software had been designed well then there wouldn't be as many edge cases.
So work hard at trying to understand the problem domain or the system you are modelling. Don't just accept a specification or set of requirements from someone else and code to that. Break down barriers between the domain experts and the software engineers; become a domain expert yourself.
