| |
September 2016 - Posts
-
In professional contexts, I think that the word "standard" has two distinct flavors.
So when we talk about a "team standard" or a "coding standard," the waters muddy a
bit. In this post, I'm going to make the case for a team standard. But
before I do, I think it important to discuss these flavors that I mention. And
keep in mind that we're not talking dictionary definition as much as the feelings
that the word evokes.
 First,
consider standard as "common." To understand what I mean, let's talk cars.
If you go to buy a car, you can have an automatic transmission or a standard transmission.
Standard represents a weird naming choice for this distinction since (1) automatic
transmissions dominate (at least in the US) and (2) "manual" or "stick-shift" offer
much better descriptions. But it's called "standard" because of historical context.
Once upon a time, automatic was a new sort of upgrade, so the existing, default option
became boringly known as "standard."
In contrast, consider standard as "discerning." Most commonly you hear this
in the context of having standards. If some leering, creepy person suggested
you go out on a date to a fast food restaurant, you might rejoin with, "ugh, no, I
have standards."
Now, take these common contexts for the word to the software team room. When
someone proposes coding standards, the two flavors make themselves plain in the team
members' reactions. Some like the idea, and think, "it's important to have standards
and take pride in our work." Others hear, "check your creativity at the gate,
because around here we write standard, default code."
What I Mean by Standard
Now that I've drawn the appropriate distinction, I feel it appropriate to make my
case. When I talk about the importance of a standard, I speak with the second
flavor of the word in mind. I speak about the team looking at its code with
a discerning attitude. Not just any code can make it in here -- we have standards.
These can take somewhat fluid forms, and I don't mean to be prescriptive. The
sorts of standards that I like to see apply to design principles as much as possible
and to cosmetic concerns only when they have to.
For example, "all non-GUI code should be test driven" and "methods with more than
20 lines should require a conversation to justify them" represent the sort of standards
I like my teams to have. They say, "we believe in TDD" and "we view long methods
as code smells," respectively. In a way, they represent the coding ethos of
the group.
On the other side of the fence lie prescriptions like, "all class fields shall be
prepended with underscores" and "all methods shall be camel case." I consider
such concerns cosmetic, since they are appearance and not design or runtime behavior.
Cosmetic concerns are not important... unless they are. If the team struggles
to read code and becomes confused because of inconsistency, then such concerns become
important. If the occasional quirk presents no serious readability issues, then
prescriptive declarations about it stifle more than they help.
Having standards for your team's work product does not mean mandating total homogeneity.
Why Have a Standard at All?
Since I'm alluding to the potentially stifling effects of a team standard, you might
reasonably ask why we should have them at all. I can assert that I'm interested
in the team being discerning, but is it really just about defining defaults?
Fair enough. I'll make my case.
First, consider something that I've already mentioned: maintenance. If the team
can easily read code, it can more easily maintain that code. Logically, then,
if the team all writes fairly similar code, they will all have an easier time reading,
and thus maintaining that code. A standard serves to nudge teams in this direction.
Another important benefit of the team standard revolves around the integrity of the
work product. Many team's standards incorporate methodology for security, error
handling, logging, etc. Thus the established standard arms the team members
with ways to ensure that the software behaves properly.
And finally, well-done standards can help less experienced team members learn their
craft. When such people join the team, they tend to look to established folks
for guidance. Sadly, those people often have the most on their plate and the
least time. The standard can thus serve as teacher by proxy, letting everyone
know the team's expectations for good code.
Forget the Conformity (by Automating)
So far, all of my rationale follows a fairly happy path. Adopt a team standard,
and reap the rewards: maintainability, better software, learning for newbies.
But equally important is avoiding the dark side of team standards. Often this
dark side takes the form of nitpicking, micromanagement and other petty bits of nastiness.
Please, please, please remember that a standard should not elevate conformity as a
virtue. It should represent shared values and protection of work product quality.
Therefore, in situations where conformity (uniformity) is justified, you should automate
it. Don't make your collaborative time about telling people where to put
spaces and brackets -- program
your IDE to do that for you.
Make Justification Part of the Standard
Another critical way to remove the authoritarian vibe from the team standard is one
that I rarely see. And that mystifies me a bit because you can do it so easily.
Simply make sure you justify each item contained in the standard.
"Methods with more than 20 line of code should prompt a conversation," might find
a home in your standard. But why not make it, "methods with more than 20 lines
of code should prompt a conversation because studies have demonstrated that defect
rate increases more than linearly with lines of code per method?" Wow, talk
about powerful.
This little addition takes the authoritarian air out of the standard, and it also
helps defuse squabbles. And, best of all, people might just learn something.
If you start doing this, you might also notice that boilerplate items in a lot of
team standards become harder to justify. "Prepend your class fields with m underscore"
becomes "prepend your class fields with m underscore because... wait, why do we do
that again?"
Prune and Always Improve
When you find yourself trailing off at because, you have a problem. Something
exists in your team standard that you can't justify. If no one can justify it,
then rip it out. Seriously, get rid of it. Having items that no one can
justify starts to put you in conformity for the sake of conformity territory.
And that's when standard goes from "discerning" to "boring."
Let this philosophy guide your standard in general. Revisit it frequently, and
audit it for valid justifications. Sometimes justifications will age out of
existence or seem lame in retrospect. When this happens, do not hesitate to
revisit, amend, or cull. The best team standards are neither boring nor static.
The best team standards reflect the evolving, growing philosophy of the team.
Related resources
Tools at your disposal
SubMain offers CodeIt.Right that
easily integrates into Visual Studio for flexible and intuitive automated code review
solution that works real-time, on demand, at the source control check-in or as part
of your build.
Learn
more how CodeIt.Right can automate your team standards and improve code quality.
About the Author
Erik Dietrich
I'm a passionate software developer and active blogger. Read about me at my
site. View
all posts by Erik Dietrich
|
-
If you write software, the term "feedback loop" might have made its way into your
vocabulary. It charts a slightly indirect route from its conception and into
the developer lexicon, though, so let's start with the term's origin. A feedback
loop in general systems uses its output as one of its inputs.
Kind of vague, huh? I'll clarify with an example. I'm actually writing
this post from a hotel room, so I can see the air conditioner from my seat.
Charlotte, North Carolina, my temporary home, boasts some pretty steamy weather this
time of year, so I'm giving the machine a workout. Its LED display reads 70
Fahrenheit, and it's cranking to make that happen.
When the AC unit hits exactly 70 degrees, as measured by its thermostat, it will take
a break. But as soon as the thermostat starts inching toward 71, it will turn
itself back on and start working again. Such is the Sisyphean struggle of climate
control.
Important for us here, though, is the mechanics of this system. The AC unit
alters the temperature in the room (its output). But it also uses the temperature
in the room as input (if < 71, do nothing, else cool the room). Climate control
in buildings operates via feedback loop.
Appropriating the Term for Software Development
It takes a bit of a cognitive leap to think of your own tradecraft in terms of feedback
loops. Most likely this happens because you become part of the system.
Most people find it harder to reason about things from within.
In software development, you complete the loop. You write code, the compiler
builds it, the OS runs it, you observe the result, and decide what to do to the code
next. The output of that system becomes the input to drive the next round.
If you have heard the term before, you've probably also heard the term "tightening
the feedback loop." Whether or not you've heard it, what people mean by this
is reducing the cycle time of the aforementioned system. People throwing that
term around look to streamline the write->build->run->write again process.
A History of Developer Feedback Loops
At the risk of sounding like a grizzled old codger, let me digress for a moment to
talk about feedback loop history. Long before my time came the punched
card era. Without belaboring the point, I'll say that this feedback loop
would astound you, the modern software developer.
Programmers would sit at key punch "kiosks", used to physically perforate forms (one
mistake, and you'd start over). They would then take these forms and have operators
turn them into cards, stacks of which they would hold onto. Next, they'd wait
in line to feed these cards into the machines, which acted as a runtime interpreter.
Often, they would have to wait up to 24 hours to see the output of what they had done.
Can you imagine? Write a bit of code, then wait for 24 hours to see if it worked.
With a feedback loop this loose, you can bet that checking and re-checking steps received
hyper-optimization.
When I went to college and started my programming career, these days had long passed.
But that doesn't mean my early days didn't involve a good bit of downtime. I
can recall modifying C files in projects I worked, and then waiting up to an hour
for the code to build and run, depending what I had changed. xkcd
immortalized this issue nearly 10 years ago, in one of its most popular comics.
Today, you don't see this as much, though certainly, you could find some legacy codebases
or juggernauts that took a while to build. Tooling, technique, modern hardware
and architectural approaches all combine to minimize this problem via tighter feedback
loops.
The Worst Feedback Loop
I have a hypothesis. I believe that a specific amount of time exists for each
person that represents the absolute, least-optimal amount of time for work feedback.
For me, it's about 40 seconds.
If I make some changes to something and see immediate results, then great. Beyond
immediacy, my impatience kicks in. I stare at the thing, I tap impatiently,
I might even hit it a little, knowing no good will come. But after about 40
seconds, I simply switch my attention elsewhere.
Now, if I know the wait time will be longer than 40 seconds, I may develop some plan.
I might pipeline my work, or carve out some other tasks with which I can be productive
while waiting. If for instance, I can get feedback on something every 10 minutes,
I'll kick it off, do some household chores, periodically checking on it.
But, at 40 seconds, it resides in some kind of middle limbo, preventing any semblance
of productivity. I kick it off and check twitter. 40 seconds turns into
5 minutes when someone posts a link to some cool astronomy site. I check back,
forget what I did, and then remember. I try again and wait 40 seconds.
This time, I look at a Buzzfeed article and waste 10 minutes as that turns into 4
Buzzfeed articles. I then hate myself.
The Importance of Tightening
Why do I offer this story about my most sub-optimal feedback period? To demonstrate
the importance of diligence in tightening the loop. Wasting a few seconds while
waiting hinders you. But waiting enough seconds to distract you with other things
slaughters your productivity.
With software development, you can get into a state of what I've heard described as
"flow." In a state of flow, the feedback loop creates harmony in what you're
doing. You make adjustments, get quick feedback, feel encouraged and productive,
which promotes more concentration, more feedback, and more productivity. You
discover a virtuous circle.
But just the slightest dropoff in the loop pops that bubble. And, another dropoff
from there (e.g. to 40 seconds for me) can render you borderline-useless. So
much of your professional performance rides on keeping the loop tight.
Tighten Your Loop Further
Modern tooling offers so many options for you. Many IDEs will perform speculative
compilation or interpretation as you code, making builds much faster. GUI components
can be rendered as you work, allowing you to see changes in real time as you alter
the markup. Unit tests slice your code into discrete, separately evaluated components,
and continuous testing tools provide pass/fail feedback as you type. Static
code analysis tools offer you code
review as you work, rather than at some code review days later. I could
go on.
The general idea here is that you should constantly seek ways to tune your day to
day work. Keep your eyes out for tools that speed up your feedback loop.
Read blogs and go to user groups. Watch your coworkers for tips and tricks.
Claw, scratch, and grapple your way to shaving time off of your feedback loop.
We've come a long way from punch cards and sword fights while code compiles.
But, in 10 or 30 years, we'll look back in amazement at how archaic our current techniques
seem. Put yourself at the forefront of that curve, and you'll distinguish yourself
as a developer.
Learn
more how CodeIt.Right can tighten the feedback loop and improve your code quality.
About the Author
Erik Dietrich
I'm a passionate software developer and active blogger. Read about me at my
site. View
all posts by Erik Dietrich
|
-
Version 5.3 of GhostDoc is a maintenance update for the v5.0 users:
-
Added full support for string interpolation in C# and VB parsers
-
Added support for "arrow functions" in JavaScript parser
-
Fixed "File is not part of a solution" issue when loading projects
-
(Pro) (Ent) Added IsAbstract property to CurrentCodeElement in the T4 templates
-
Improved exception documentation - now the type name in a nameof() parameter is added
as part of the generated documentation template
-
(Ent) Fixed iue when using <section> along with <code> elements in an
.aml file
For the complete list of changes, please see What's
New in GhostDoc v5
For overview of the v5.0 features, visit Overview
of GhostDoc v5.0 Features
Download the new build at http://submain.com/download/ghostdoc/
|
-
Think back to college (or high school, if applicable). Do you remember that
kid that would sit near the front of the class and gleefully point out that the professor
had accidentally omitted an apostrophe when writing notes on the white board?
Didn't you just love that kid? Yeah, me neither.
Fate imbues a small percentage of the population with a neurotic need to correct any
perceived mistakes made by anyone. XKCD immortalized this phenomenon with one
of its most famous cartoons, that declared, "someone
is wrong on the internet." For the rest of the population, however, this
tendency seems pedantic and, dare I say, unpleasant. Just let it go, man.
It doesn't matter that much.
I mention all of this to add context to the remainder of the post. I work as
a consultant and understand the need for diplomacy, tact, and choosing one's battles.
So, I do not propose something like care with spelling lightly. But I will propose
it, nonetheless.
Now I know what you're thinking. How can caring about spelling in code be anything
but pedantic? We're not talking about something being put together to impress
a wide audience, like a newspaper. In fact, we're not even talking about prose.
And code contains all sorts of abbreviations and encodings and whatnot.
Nevertheless, it matters. When English words occur in your code, spelling them
right matters. I'll use the rest of this post to make my case.
The IntelliSense Conundrum
If you use Visual Studio, no doubt you make heavy use of IntelliSense.
To expand, any IDE or text editor with autocomplete functionality qualifies for consideration
here. In either case, your tooling gives you a pretty substantial boost by suggesting
methods/variables/classes/etc based on what you have typed. It's like type-ahead
for code.
Now think of the effect a misspelling can have here, particularly near the beginning
of a word. Imagine implementing a method that would release resources and accidentally
typing Colse instead of Close.
Now imagine consuming that method. If you're used to exploring APIs and available
methods with auto-complete, you might type, "Clo", pause, and see no matching methods.
You might then conclude, "hey, no call to Close needed!"
In all likelihood, such an error would result in a few minutes of head-scratching
and then the right call. But even if that's the worst of it, that's still not
great. And it will happen each and every time someone uses your code.
Other Manual Typing Errors
The scope of this particular issue goes beyond auto-complete functionality.
Perhaps you lack that functionality in your environment, or perhaps you simply don't
use it much. In that case, you'll be hand typing your code.
Now, imagine hand typing the call above to a close method. Do you instinctively
type "Colse" or do you instinctively type "Close?" So what do you think will
happen?
You'll expect the call to be Close and you'll type that. Then, you'll stare
in disbelief for a moment at the compiler message. You'll probably do a clean
and rebuild. You'll stare again for a while and squint. Then, finally,
you'll smack your forehead, realize the problem, and silently berate the person who
misspelled the method name.
Again, the impact remains the same. Most likely this creates only friction and
annoyance. Every now and then, it may trigger a thoroughly incorrect use of
a library or API.
Anchoring Effect
Moving away from the theme of confusion when using a declared member, consider the
declaration itself. During the use of a variable/method/class/etc, you must
spell it right before the compiler allows you to proceed (assuming a strongly typed
language). With the original declaration, however, you have the freedom to spell
things wrong to your heart's content. When you do this, the original copy holds
the error.
That first misspelling allows for easy correction. Same goes when you've used
it only a time or two. But as usage grows and spreads throughout the codebase,
the fix becomes more and more of a chore. Before long (and without easy refactoring
tools), the chore becomes more than anyone feels like tackling, and the error calcifies
in place.
Your unaddressed spelling mistake today makes fixes more difficult tomorrow.
Comprehension Confusion
Let's switch gears again and consider the case of a maintenance programmer reading
for comprehension. After all, programmers do a whole lot more reading of code
than they do modification of it. So, a casual read is a likely situation.
Spelling errors cloud comprehension. A simple transposition of characters or
a common error, such as referring to a "dependency" do not present an insurmountable
problem. But a truly mangled word can leave readers scratching their heads and
wondering what the code actually means, almost as if you'd left some kind of brutal
Hungarian notation in there.
Taking the time to get the spelling right ensures that anyone maintaining the code
will not have this difficulty. Code is hard enough to understand, as-is, without
adding unforced errors to the mix.
The Embarrassment Factor
And, finally, there's the embarrassment factor. And I don't mean the embarrassment
of your coworkers saying, "wow, that guy doesn't know how to spell!" I'm talking
about the embarrassment factor for the team.
Think of new developers hiring on or transferring into the group. They're going
to take a look at the code and draw conclusions, about your team. Software developers
tend to have exacting, detail-oriented minds, and they tend to notice mistakes.
Having a bunch of spelling mistakes in common words makes it appear either that the
team doesn't know how to spell or that it has a sloppy approach. Neither of
those is great.
But also keep in mind that what happens in the code doesn't always stay in the code.
Bits of the code you write might appear on team dashboards, build reports, unit test
run outputs, etc. People from outside of the team may be examining acceptance
tests and the like. And, you may have end-user documentation generated automatically
using your code (i.e. if you make developer tools or APIs). Do you really want
the documentation you hand to your customers to contain embarrassing mistakes?
It's Easy to Get Right
At this point, I'm finished with the supply of arguments for making the case.
I've laid these out.
But, by way of closing words, I'd like to comment on what might be the biggest shame
of the whole thing. Purging your code of spelling errors doesn't require you
to be an expert speller. It doesn't require you to copy source code into MS
Word or something and run a check. You have tools at your disposal that will
do this for you, right
in your IDE. All you need to do is turn them on.
I recommend that you do this immediately. It's easy, unobtrusive, and offers
only upside. And not only will you excise spelling mistakes from your code --
you'll also prevent that annoying kid in the front of the class from bothering you
about stuff you don't have time for.
Learn
more about GhostDoc's truly source code spell checker and eliminate embarrassing
typos in your apps and documentation before you ship them.
About the Author
Erik Dietrich
I'm a passionate software developer and active blogger. Read about me at my
site. View
all posts by Erik Dietrich
|
|
|
|
|
|
|