Those to Come
As a developer, what do I owe to other developers that may come behind me?
It’s not as straightforward a question as you may think initially. The question has been coming up with me a lot recently, and there seem to be two distinct schools of thought:
- Your code should be readable, and well-documented.
- Your code should be well-documented, and exclusively employ patterns and tactics that are familiar to your intended ‘audience.’
The difference between these two camps is the definition of the term ‘readable.’ In the former, it’s intentionally vague. People who ascribe to that camp don’t feel that ‘readibility’ is easily defined, and acknowledge that it varies from person to person (e.g. what is readable to a seasoned Perl developer will most certainly be gibberish to someone whose main body of work has been in Java). The second group takes a much more proactive approach by defining readibility to include familiarity.
So what’s the big deal, if the answers are so similar?
First, a disclaimer. I hold to Occam’s razor when developing as a matter of principle. No, I’m not referring to the watered-down, Contact-ized rendition of Occam’s razor - I mean that I do my best to avoid unnecessary complexity. I am not about to embark on a discussion of whether or not it matters if I do fancy stuff with my code - the ‘magic’ that catches flak for rails from some people. Instead, I want to consider cases of ‘proper’ solutions vs. ‘common’ solutions.
Proper solutions are solutions that are objectively the best solution for the job. If the job requires speed, this is the fastest solution. If the job requires stability, this is the most stable. All else being equal, if the application is object-oriented, this is the solution that best maps the problem space to the object pattern in use.
More often than not, these solutions are the same as the ‘common’ solutions. There are, however, a few cases where they are different. Consider, for example, the following question: in an object-oriented model describing a hierarchy of employees, should your Manager object extend your Employee object?
Most people will say yes to that question. However, it’s not necessarily that straightforward. This is one of those areas where, in certain situations, the ‘common’ solution differs from the ‘proper’ one.
This is where the camps diverge. In this scenario the first camp acknowledges the proper solution, documents it thoroughly, and washes their hands of the situation (after all the bugs are resolved, at least). The second camp similarly acknowledges the proper solution, but notes that most people aren’t familiar with the logic behind it; as that makes the common solution more ‘readable’ in their eyes, they code the common solution, document it thoroughly, and wash their hands of the situation.
They both seem appealing arguments, but let me throw a wrench in the works: if someone can’t understand the proper solution to a problem, should they be working on the problem in the first place?
An analogous situation that is a bit more obviously flawed would be asking a professional, doctorate-level economist to be sure he only employs theories in his work that are understandable by an undergraduate student in the field. Foregoing his great understanding of the market forces, he is reduced to explaining everything in terms of vaguely-vetted supply and demand curves. In other words, the quality of his work would suffer, greatly in situations where the undergraduate understanding of the field does not map accurately to the actual problem, and all for the sake of someone who is not qualified to be dealing with his work (professionally).
And yet, given this choice with developers, most companies will encourage the second viewpoint. Is it me, or is hamstringing your code for the benefit of someone unqualified to solve the problem obviously detrimental?