There are plenty of articles available for advice on writing clean and clear code. Many of the general principles are easy to grasp: short methods, straightforward logic and flow, clear and unambiguous variable names, consistent terminology usage, etc.
All of these
things make your code easier to read, to understand, and ultimately to maintain
and change. A good programmer knows that writing something clever and cool
doesn't necessarily mean it was written the best way, even if it makes the code
smaller. There are certainly limits to this (no one would argue much if you
turns a 200 line class into 2 lines, even if those 2 lines weren't the clearest
in the world, for example) but the point stands. There are 1000 ways to write
code for a given feature, and there is no one true 'right' way for anything.
Which brings me to
my point: a lot of times, writing something 'clever' may not be as good in the
long run as writing something 'simple'. That abstract class filled with generic
methods and callback delegates may get the job done and then some, may allow
you to easily extend it and do anything you might ever have to do, but it's
probably not easy to pick up and understand at a glance. We can set aside the
benefits/risks of violating YAGNI in my example; it's worth addressing, but
that's not my focus here.
In many cases, I
try to keep my code as simple as I can. The analogy I try to about is a
newspaper; in order to reach and be read and understood by the masses, most
papers will dumb down their verbiage in order to be better understood.
Similarly, I try and write my code so that a majority of it can be picked up
and read by entry level programmers.
That's not to say
don't used advanced programming techniques, but I know a lot of people who will
use them because they are 'neat' or 'clever' or any other word that describes
using it because it's interesting and not necessarily because it is the right
tool for the job. There is nothing wrong with an if-else, a switch, or a
foreach loop, and basic overloading or overriding of methods can get you very
far. The keys to clear code lie in intelligent naming and intuitive methods.
Few people will
look at this and not get the basic idea of what you are trying to do:
public void OnClick(int id)
{
var ball = GetClickedBallById(id);
ball.Roll(Units.Yards, 10, Direction.East);
}
private Ball GetClickedBallById(int id)
{
foreach(var ball in ballList)
{
if (ball.Id == id)
return ball;
}
return null;
}
But some, especially new programmers or those unfamiliar with the code, might scratch heads at something like this:
public void Clicker(int i)
{
Get<int>(i).Execute(2, 10, 1);
}
private BaseClass Get<T>(T i)
{
return objList
.Where(o => o.Id == i)
.FirstOrDefault();
}
Now, I'm not
saying I hate generics or Linq, because actually I don't, and they definitely
have a place and can be very intuitive. This is just an example, and an
observation that more people will quickly understand a foreach loop with a
couple of if statements than a possibly complex where clause in a Linq lambda.
I know in reviewing my own code after the fact, sometimes what seemed like a
really helpful and clever replacement would come back and bite me when I needed
to tweak some minor functionality in that loop that I hadn't considered
originally.
Every developer
should ask themselves some questions in the above example: does killing those
4-5 lines make the code harder to read? Is there any way I can fix that? Is
there a middle ground between clarity and concise code? How much do I expect my
programmers to understand when they pick up the code? What about the BAs, or
managers?
Don't be afraid to
dumb down in the interest of clarify. There's nothing stopping you from
refactoring it later into some super-generic-awesomeness if you REALLY feel you
need it, and that it actually helps your code.
Happy coding!
