Over the last year, I've ended up on four projects that were started prior to my arrival. This isn't uncommon; more often than not throughout any c...
For further actions, you may consider blocking this person and/or reporting abuse
Nice article David. This is a great, under represented topic that has bigger consequences than most developers realize as it can lead to failed projects.
Some developers never take time to refactor and simplify their code usually because they don't see a cost benefit, want to implement the next feature with minimal effort, or do not want to deal with the time, communication, and risk of a breaking change. Sometimes a developer has a photographic memory and can remember all the details but the dev behind them doesn't have the benefit of knowing how it was built. The result of this over time is code that they as you indirectly referenced above and the next developers behind them have great difficulty working with. It also hurts their reputation inside the company as someone who generates code that is difficult to work with.
The rule I follow and what I encourage developers working with me is to first get it to work, then clean it up ensuring all parameters are in the configuration file, and all objects, methods, and vars are named to exactly match what they do. Cleaning up later is difficult as the code is no longer fresh in the developers mind and if not done soon afterwards will never get done. Then developers behind them, like yourself, rightfully complain about the code. This is a common issue that has been happening for decades.
A more compelling reason to create easy to understand code is for you as a developer to keep your job, improve your reputation, and ultimately to enjoy the benefits of a long career.
John
Thanks John, I very much agree. And yes, the "it can lead to failed projects" point is incredibly important; especially if you're working for an organisation for whom software delivery isn't their primary function; because, as experienced on the project I describe above, product owners who are not familiar with software development will often not appreciate how big of a task it can be to get up to speed with someone else's project when these considerations haven't been made during its development.
Of course there are often pressures on development teams to get things done as quickly as possible; but we need to appreciate that a small time investment in this area actually allows everyone to get things done more quickly overall. I'm not suggesting this is by any means a new idea, nor a new problem, but sometimes it's worth a reminder. :D
John, I'm sorry. I do not agree that the process should be write nasty code then clean it up. The problem is that the second step probably won't occur - leaving nasty code.
It is far better to insist that clean, understandable code be written in the first place. I bemoan the fact that today we employ entry level programmers to design and implement new code. In the past, we employed new programmer as maintenance programmers who leaned the hard way that poorly written code was to be avoided.
Personally, I advocate coding your comments wherever possible. For example:
should (IMO) be
The only time comments are really appropriate (again, IMO) is for explaining why something's happening which you think is "a bit weird", which in my experience, is down to weird business logic basically 100% of the time. In those situations, yes, do write a comment. But definitely default to trying to code any comments you can!
Really like your point to think about the next developer. Please make sure code can be read in the future, or in other words be maintained by you or others. In order to nail the question how to measure the maintainability of code we share & validate 10 simple guidelines via bettercodehub.com a GitHub integration that is free for open source. We see that these guidelines are easy to learn but difficult to adhere to during sprints. Also any guidelines should not be enforced blindly (resulting in a violation flood), they should be applied to the complete code base and against a large benchmark. Measuring in that way introduces tolerance and provides a Definition of Done. So the developer can think about himself too!
Michiel
Michiel, I think the link is broken. Would be interested to see the guidelines.
Bob, thanks for finding that broken link. The 10 guidelines are in this O'Reilly book Building Maintainable Software and also implemented in BetterCodeHub.com It runs for free with you GitHub handle.
The new version looks beautiful. I wish I had practiced self-documenting code when I was still coding. There's a good checklist here: sitepoint.com/self-documenting-jav...
I would add wrapping any Regex or Xpath in a function with a name in normal language.
Thanks for writing this David. Each and every organisation has this problem and has tackled it with varying degrees of success.
Situitions like this make me pine for programming in BASIC. Anyone could read it and understand what was going on. And that is a very powerful draw.
Thanks again for highlighting this.
@K_Fistman does not exist on Twitter!
I know! Changed my Twitter handle to @_dnimmo but I can't see a way to change it in my settings here. :-(
Hmm we didn't think of that edge case. I'll fix it for you now and make sure it syncs in the future 🙂
Thanks for sorting this out for me. :-)
Great article! In fact, my company just covered this on our latest podcast: dev.to/mousepaw/episode-4-new-char...