SubMain - CodeIt.Right The First Time!


Support Community for SubMain Products
 Home Products Services Download Purchase Support
in Search
Home Forums Blogs Tutorials/CIR Tutorials/GD Downloads
Welcome to SubMain Community Sign in | Join | Help

SubMain Blog

  • How C# Spell Check Helps Your Team and Your Code

    If you didn’t know that C# spell check was a thing, it is.  For one thing, you can run a normal spelling analysis on any comments in your code.  That shouldn’t surprise.  But you can also check the code itself for spelling errors. That may seem like a strange thing at first.  Wouldn’t a C#...

    The post How C# Spell Check Helps Your Team and Your Code appeared first on Software Quality Blog - SubMain Software.

  • GhostDoc Pro Beta brings true Visual Editing to XML Comments

    The latest Beta of GhostDoc introduces a new feature that makes XML documentation authoring a breeze – Visual Edition for XML Comments. The number one challenge authoring XML Comments that we heard from our users has been keeping the valid XML which includes encoding HTML formatting tags, code samples, etc. Many of these don’t even...
  • Spring Cleaning Your Code Review

    Many of us have a natural tendency to let little things pile up.  This gives rise to the notion of the so-called spring cleaning.  The weather turns warm and going outside becomes reasonable, so we take the opportunity to do some kind of deep cleaning. blog-spring-cleaning-your-code-review

    Of course, this may not apply to you.  Perhaps you keep your house impeccable at all times, or maybe you simply have a cleaning service.  But I'll bet that, in some part of your life or another, you put little things off until they become bigger things.  Your cruft may not involve dusty shelves and pockets of house clutter, but it probably exists somewhere.

    Maybe it exists in your professional life in some capacity.  Perhaps you have a string of half written blog posts, or your inbox has more than a thousand messages.  And, if you examine things honestly, you almost certainly have some item that has been skulking around your to-do list for months.  Somewhere, we all have items that could use some tidying, cognitive or physical.

    With that in mind, I'd like to talk about your code review process.  Have you been executing it like clockwork for months or years?  Perhaps it has become too much like clockwork.  Turn a critical eye to it, and you might realize elements of it have become stale or superfluous.  So let's take a look at how you can apply a spring cleaning to your code review process.

    Beware The Cargo Cult

    During World War II, the Allies set up a temporary air base on an island in the Pacific Ocean.  The people living on the Island observed the ground controllers waving at inbound planes to help them land.  Supplies then followed.  Not understand the purpose of this ritual or the mechanics of airplanes, the locals learned that making these motions brought planes with supplies.  So after the allies left, they mimicked the behavior, hoping for additional resources.  This execution of ritual without understanding earned the designation "cargo cult."

    In the world of software development, cargo cult programming involves adding code without understanding what it does.  You added it once, good things happened, so now you always add it.  You can think of this as a special case of programming by coincidence.  And it's something you should avoid.

    But cargo cult mentality can crop up in a code review as well.  Do you find your team calling out 'issues' during the review, but, if pressed, nobody could articulate why those are issues?  If so, you have a cargo cult practice, and you should cull it.

    Going Over the Same Stuff Repetitively

    Let's say that your team performs code review on a regular basis.  Does this involve an ongoing, constant uplift?  In other words, do you find learning spreads among the team, and you collectively sharpen your game and constantly improve?  Or do you find that the team calls out the same old issues again and again?

    If every code review involves noticing a method parameter dereference and saying, "you'll get an exception if someone passes in null," then you have stagnation.  Think of this as a team smell.  Why do people keep making the same mistake over and over again?  Why haven't you somehow operationalized a remedy?  And, couldn't someone have automated this?

    Keep an eye out for this sort of thing.  If you notice it, pause and do some root cause analysis.  Don't just fix the issue itself -- fix it so the issue stops happening.

    Inconsistency in Reviews

    Another common source of woe arises from inconsistency in the code review process.  Not only does this result in potential issues within the code, but it also threatens to demoralize members of the team.  Imagine attending a review and having someone admonish you to add logging calls to all of your methods.  But then, during the next review, someone gives you a hard time about logging too much.  Enough of that nonsense and team members start updating their resumes rather than their methods.

    And inconsistency can mean more than just different review styles from different people (or the same person on different days, varying by mood).  You might find that your team's behavior and suggestions during review have become out of sync with a formal document like the team's coding standard.  Whatever the source, inconsistency creates drag for your team.

    Take the opportunity of a metaphorical spring cleaning to address this potential pitfall.  Round up the team members and make sure they all have the same philosophies at code review time.  And then, make sure that unified philosophy lines up with anything documented.

    Cut Out the Nitpicking

    I've yet to see an organization where interpersonal code review didn't become at least a little political.  That makes sense, of course.  In essence, you're talking about an activity where people get together and offer (hopefully) constructive professional criticism.

    Because of the politics, personal code review can degenerate and lead to infighting in numerous ways.  Chief among these, I've found, is excessive nitpicking.  If team members perceive the activity as a never ending string of officious criticism, they start to hate coming to work.

    On top of that, people can only internalize so many lessons in a sitting.  After a while, they start to tune out or get tired.  So make the takeaways from the code review count.  Even if they haven't gotten every little thing just so, pick your battles and focus on big things.  And I file this under spring cleaning since it generally requires a concerted mental adjustment and since it will clear some of the cruft out of your review.

    Automate, Automate, Automate

    I will conclude by offering what I consider the most important item for any code review spring cleaning.  If the other suggestions in involved metaphorical shelf dusting and shower scrubbing, think of this one as completely cleaning out an entire room that you had loaded with junk.

    So much of the time teams spend in code review seems to trend toward picking at nits.  But even when it involves more substantive considerations, many of these considerations could be automatically detected.  The team wastes precious time peering at the code and playing static analyzer.  Stop this!

    Spruce up your review process by automating as much of it as humanly possible.  You should constantly ask yourself if the issue you're discussing could be automatically detected (and fixed).  If you think it could, then do it.  And, as part of your spring cleaning, knock out as many of these as possible.

    Save human-centric code review for focus on design considerations, architectural discussions, and big picture issues.  Don't bog yourself down in cruft.  You'll all feel a lot cleaner and happier for it, just as you would after any spring cleaning.

    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.

    Related resources

    Learn more how CodeIt.Right can help you automate code reviews and improve the quality of your code.

    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

  • CodeIt.Right Rules Explained, Part 5

    Today, I'll do another installment of the CodeIt.Right Rules, Explained series.  This is post number five in the series.  And, as always, I'll start off by citing my two personal rules about static analysis guidance, along with the explanation for them.

    • Never implement a suggested fix without knowing what makes it a fix.
    • Never ignore a suggested fix without understanding what makes it a fix.

    It may seem as though I'm playing rhetorical games here.  After all, I could simply say, "learn the reasoning behind all suggested fixes."  But I want to underscore the decision you face when confronted with static analysis feedback.  In all cases, you must actively choose to ignore the feedback or address it.  And for both options, you need to understand the logic behind the suggestion.

    In that spirit, I'm going to offer up explanations for three more CodeIt.Right rules today.

    Mark ISerializable Types with "Serializable" Attribute

    If you run across this rule, you might do so while writing an exception class.  For example, the following small bit of code in a project of mine triggers it.

    public class GithubQueryingException
    : Exception { public GithubQueryingException(string message,
    Exception ex) : base(message,
    ex) { } }

    It seems pretty innocuous, right?  Well, let's take a look at what went wrong.

    The rule actually describes its own solution pretty well.  Slap a serializable attribute on this exception class and make the tool happy.  But who cares?  Why does it matter if you don't mark the exception as serializable?

    To understand the issue, you need awareness of a concept called "application domains" within the .NET framework.  Going into much detail about this would take us beyond the scope of the post.  But suffice it to say, "application domains provide an isolation boundary for security, reliability, and versioning, and for unloading assemblies."  Think two separate processes running and collaborating.

    If some external process will call your code, it won't access and deal with your objects the same way that your own code will.  Instead, it needs to communicate by serializing the object and passing it along as if over some remote service call.  In the case of the exception above, it lacks the attribute marking it explicitly as serializable, in spite of implementing that interface.  So bad things will happen at runtime.  And this warning exists to give you the heads up.

    If you'll only ever handle this exception within the same app domain, it won't cause you any heartburn.  But, then again, neither will adding an attribute to your class.

    Do Not Handle Non-CLS-Compliant Exceptions

    Have you ever written code that looks something like this?

    try {
    DoSomething(); return true;
    } catch { return false;

    In essence, you want to take a stab at doing something and return true if it goes well and false if anything goes wrong.  So you write code that looks something like the above.

    If you you have, you'll run afoul of the CodeIt.Right rule, "do not handle non-cls-compliant exceptions."  You might find this confusing at first blush, particularly if you code exclusively in C# or Visual Basic.  This would confuse you because you cannot throw exceptions not compliant with the common language specification (CLS).  All exceptions you throw inherit from the Exception class and thus conform.

    However, in the case of native code written in, say, C++, you can actually throw non-CLS-compliant exceptions.  And this code will catch them because you've said "catch anything that comes my way."  This earns you a warning.

    The CodeIt.Right warning here resembles one telling you not to catch the general exception type.  You want to be intentional about what exceptions you trap, rather than casting an overly wide net.  You can fix this easily enough by specifying the actual exception you anticipate might occur.

    Async Methods Should Return Task or Task<T>

    As of .NET Framework 4.5, you can use the async keyword to allow invocation of an asynchronous operation.  For example, imagine that you had a desktop GUI app and you wanted to populate a form with data.  But imagine that acquiring said data involved doing an expensive and time consuming call over a network.

    With synchronous programming, the call out to the network would block, meaning that everything else would grind to a halt to wait on the network call... including the GUI's responsiveness.  That makes for a terrible user experience.  Of course, we solved this problem long before the existence of the async keyword.  But we used laborious threading solutions to do that, whereas the async keyword makes this more intuitive.

    Roughly speaking, designating a method as "async" indicates that you can dispatch it to conduct its business while you move on to do other things.  To accomplish this, the method synchronously returns something called a Task, which acts as a placeholder and a promise of sorts.  The calling method keeps a reference to the Task and can use it to get at the result of the method, once the asynchronous operation completes.

    But that only works if you return a Task or Task<T>.  If, instead, you create a void method and label it asynchronous, you have no means to get at it later and no means to explicitly wait on it.  There's a good chance this isn't what you want to do, and CodeIt.Right lets you know that.  In the case of an event handler, you might actually want to do this, but better safe than sorry.  You can fix the violation by returning a non-parameterized Task rather than declaring the method void.

    Until Next Time

    This post covered some interesting language and framework features.  We looked at the effect of crossing app domain boundaries and what that does to the objects whose structure you can easily take for granted.  Then we went off the beaten path a little by looking at something unexpected that can happen at the intersection of managed and native code.  And, finally, we delved into asynchronous programming a bit.

    As we wander through some of these relatively far-reaching concerns, it's nice to see that CodeIt.Right helps us keep track.  A good analysis tool not only helps you catch mistakes, but it also helps you expand your understanding of the language and framework.

    Learn more how CodeIt.Right can help you automate code reviews 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

  • Automated Code Review to Help with the Unknowns of Offshore Work

    I like variety.  In pursuit of this preference, I spend some time management consulting with enterprise clients and some time volunteering for "office hours" at a startup incubator.  Generally, this amounts to serving as "rent-a-CTO" for startup founders in half hour blocks.  This provides me with the spice of life, I guess.

    As disparate as these advice forums might seem, they often share a common theme.  Both in the impressive enterprise buildings and the startup incubator conference rooms, people ask me about offshoring application development.  To go overseas or not to go overseas?  That, quite frequently, is the question (posed to me).

    I find this pretty difficult to answer absent additional information.  In any context, people asking this bake two core assumptions into their question.  What they really want to say would sound more like this.  "Will I suffer for the choice to sacrifice quality to save money?"

    They assume first that cheaper offshore work means lower quality.  And then they assume that you can trade quality for cost as if adjusting the volume dial in your car.  If only life worked this simply.

    What You Know When You Offshore

    Before going further, let's back up a bit.  I want to talk about what you actually know when you make the decision to pay overseas firms a lower rate to build software.  But first, let's dispel these assumptions that nobody can really justify.

    Understand something unequivocally.  You cannot simply exchange units of "quality" for currency.  If you ask me to build you a web app, and I tell you that I'll do it for $30,000, you can't simply say, "I'll give you $15,000 to build one-half as good."  I mean, you could say that.  But you'd be saying something absurd, and you know it.  You can reasonably adjust cost by cutting scope, but not by assuming that "half as good" means "twice as fast."

    Also, you need to understand that "cheap overseas labor" doesn't necessarily mean lower quality.  Frequently it does, but not always.  And, not even frequently enough that you can just bank on it.

    So what do you know when you contract with an inexpensive, overseas provider?  Not a lot, actually.  But you do know that your partner will work with you mainly remotely, across a great deal of distance, and with significant communication obstacles.  You will not collaborate as closely with them as you would with an employee or a local vendor.

    The (Non) Locality Conundrum

    So you have a limited budget, and you go shopping for offshore app dev.  You go in knowing that you may deal with less skilled developers.  But honestly, most people dramatically overestimate the importance of that concern.

    What tends to torpedo these projects lies more in the communication gulf and less in the skill.  You give them wireframes and vague instructions, and they come back with what they think you want.  They explain their deliveries with passable English in emails sent at 2:30 AM your time.  This collaboration proves taxing for both parties, so you both avoid it, for the most part.  You thus mutually collude to raise the stakes with each passing week.

    Disaster then strikes at the end.  In a big bang, they deliver what they think you want, and it doesn't fit your expectations.  Or it fits your expectations, but you can't build on top of it.  You may later, using some revisionist history, consider this a matter of "software quality" but that misses the point.

    Your problem really lies in the non-locality, both geographically and more philosophically.

    When Software Projects Work

    Software projects work well with a tight feedback loop.  The entire agile movement rests firmly atop this premise.  Stop shipping software once per year, and start shipping it once per week.  See what the customer/stakeholder thinks and course correct before it's too late.  This helps facilitate success far more than the vague notion of quality.

    The locality issue detracts from the willingness to collaborate.  It encourages you to work in silos and save feedback for a later date.  It invites disaster.

    To avoid this, you need to figure out a way to remove unknowns from the equation.  You need to know what your partner is doing from week to week.  And you need to know the nature of what they're building.  Have they assembled throwaway, prototype code?  Or do you have the foundation of the future?

    Getting a Glimpse

    At this point, the course for enterprises and startups diverge.  The enterprise has legions of software developers and can easily afford to fly to Eastern Europe or Southeast Asia or wherever the work gets done.  They want to leverage economies of scale to save money as a matter of policy.

    The startup or small business, on the other hand, lacks these resources.  They can't just ask their legion of developers to review the offshore work more frequently.  And they certainly can't book a few business class tickets over there to check it out for themselves.  They need to get more creative.

    In fact, some of the startup founders I counsel have a pretty bleak outlook here.  They have no one in their organization in a position to review code at all.  So they rely on an offshore partner for budget reasons, and they rely on that partner as expert adviser and service provider.  They put all of their eggs in that vendor's basket.  And they come to me asking, "have I made a good choice?"

    They need a glimpse into what these offshore folks are doing, and one that they can understand.

    Leveraging Automated Code Review

    While you can't address the nebulous, subjective concept of "quality" wholesale, you can ascertain properties of code.  And you can even do it without a great deal of technical knowledge, yourself.  You could simply take their source code and run an automated code review on it.

    You're probably thinking that this seems a bit reductionist.  Make no mistake -- it's quite reductionist.  But it also beats no feedback at all.

    You could approach this by running the review on each incremental delivery.  Ask them to explain instances where it runs afoul of the tool.  Then keep doing it to see if they improve.  Or, you could ask them to incorporate the tool into their own process and make delivering issue-free code a part of the contract.  Neither of these things guarantees a successful result.  But at least it offers you something -- anything -- to help you evaluate the work, short of in-depth knowledge and study yourself.

    Recall what I said earlier about how enterprises regard quality.  It's not as much about intrinsic properties, nor is it inversely proportional to cost.  Instead, quality shows itself in the presence of a tight feedback loop and the ability to sustain adding more and more capabilities.  With limited time and knowledge, automated code review gives you a way to tighten that feedback loop and align expectations.  It ensures at least some oversight, and it aligns the work they do with what you might expect from firms that know their business.

    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.

    Related resources

    Learn more how CodeIt.Right can help you automate code reviews and ensure the quality of delivered code.

    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

  • Transitioning from Manual to Automated Code Review

    I can almost sense the indignation from some of you.  You read the title and then began to seethe a little.  Then you clicked the link to see what kind sophistry awaited you.  "There is no substitute for peer review."

    Relax.  I agree with you.  In fact, I think that any robust review process should include a healthy amount of human and automated review.  And, of course, you also need your test pyramid, integration and deployment strategies, and the whole nine yards.  Having a truly mature software shop takes a great deal of work and involves standing on the shoulders of giants.  So, please, give me a little latitude with the premise of the post.

    Today I want to talk about how one could replace manual code review with automated code review only, should the need arise.

    Why Would The Need for This Arise?

    You might struggle to imagine why this would ever prove necessary.  Those of you with many years logged in the enterprise in particular probably find this puzzling.  But you might find manual code inspection axed from your process for any number of reasons other than, "we've decided we don't value the activity."

    First and most egregiously, a team's manager might come along with an eye toward cost savings.  "I need you to spend less time reading code and more time writing it!"  In that case, you'll need to move away from the practice, and going toward automation beats abandoning it altogether.  Of course, if that happens, I also recommend dusting off your resume.  In the first place, you have a penny-wise, pound-foolish manager.  And, secondly, management shouldn't micromanage you at this level.  Figuring out how to deliver good software should be your responsibility.

    But let's consider less unfortunate situations.  Perhaps you currently work in a team of 2, and number 2 just handed in her two weeks’ notice.  Even if your organization back-fills your erstwhile teammate, you have some time before the newbie can meaningfully review your code.  Or, perhaps you work for a larger team, but everyone gradually becomes so busy and fragmented in responsibility as not to have the time for much manual peer review.

    In my travels, this last case actually happens pretty frequently.  And then you have to choose: abandon the practice altogether, or move toward an automated version.  Pretty easy choice, if you ask me.

    First, Take Inventory

    Assuming no one has yet forced your hand, pause to take inventory.  What currently happens as part of your review process?  What sorts of feedback do you get?

    If your reviews happen in some kind of asynchronous format, then great.  This should prove easy enough to capture since you'll need only to go through your emails or issues list or whatever you use.  Do you have in-person reviews, but chronicle the findings?  Just as good for our purposes here.

    But if these reviews happen in more ad hoc fashion, then you have some work to do.  Start documenting the feedback and resultant action items.  After all, in order to create a suitable replacement strategy for an activity, you must first thoroughly understand that activity.

    Automate the Automate-able

    With your list in place, you can now start figuring out how to replace your expiring manual process.  First up, identify the things you can easily automate that come up during reviews.

    This will include cosmetic concerns.  Does your code comply with the team standard?  Does it comply with typical styling for your tech stack?  Have you consistently cased and named things?  If that stuff comes up during your reviews, you should probably automate it anyway and not waste time discussing it.  But, going forward, you will need to automate it.

    But you should also look for anything that you can leverage automation to catch.  Do you talk about methods getting too long or about not checking parameters for null before dereferencing?  You can also automate things like that.  How about compliance with non-cosmetic best practices?  Automate that as well with an automated code review tool.

    And spend some time researching what you can automate.  Even if no analyzer or review tool catches something out of the box, you can often customize them to catch it (or write your own thing, if needed).

    Checks and Balances for Conceptual Items

    Now, we move onto the more difficult things.  "This method seems pretty unreadable."  "Couldn't you use the builder pattern here?"  I'm talking here about the sorts of things for which manual code review really shines and serves its purpose.  You'll have a harder time replacing this.  But that doesn't mean you can't do something.

    First, I recommend that you audit the review history you've been compiling.  See what comes up the most frequently, and make a list of those things.  And group them conceptually.  If you see a lot of "couldn't you use Builder" and "couldn't you use Factory Method," then generalize to "couldn't you use a design pattern?"

    Once you have this list, if nothing else, you can use it as a checklist for yourself each time you commit code.  But you might also see whether you can conceive of some sort of automation.  Or maybe you just resolve to revisit the codebase periodically, with a critical eye toward these sorts of questions.

    You need to see if you can replace the human insights of a peer.  Admittedly, this presents a serious challenge.  But get creative and see what you can come up with.

    Adjust Your Approach

    The final plank I'll mention involves changing the way you approach development and review in general.  For whatever reason, human review of your work has become a scarce resource.  You need to adjust accordingly.

    Picking up a good bit of automated review makes up part of this adjustment, as does creating of a checklist to apply to yourself.  But you need to go further as well.  Take an approach wherein you look to become more self-sufficient for any of the littler things and store up your scarce access to human reviewers for the truly weighty architectural decisions.  When these come up, enlist the help of someone else in your organization or even the internet.

    On top of that, look opportunistically for ways to catch your own mistakes and improve.  Everyone has to learn from their mistakes, but with less margin for error, you need to learn from them and automate their prevention going forward.  Again, automated review helps here, but you'll need to get creative.

    Having peer review yanked out from under you undeniably presents a challenge.  Luckily, however, you have more tools than ever at your disposal to pick up the slack.  Make use of them.  When you find yourself in a situation with the peer review safety net restored, you'll be an even better programmer for it.

    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.

    Related resources

    Learn more how CodeIt.Right can help you automate code reviews 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

  • Static Analysis to Hide My Ignorance about Global Concerns

    "You never concatenate strings.  Instead, always use a StringBuilder."

    I feel pretty confident that any C# developer that has ever worked in a group has heard this admonition at least once.  This represents one of those bits of developer wisdom that the world expects you to just memorize.  Over the course of your career, these add up.  And once they do, grizzled veterans engage in a sort of comparative jousting for rank.  The internet encourages them and eggs them on.

    "How can you call yourself a senior C# developer and not know how to serialize objects to XML?!"

    With two evenly matched veterans swinging language swords at one another, this volley may continue for a while.  Eventually, though, one falters and pecking order is established.

    Static Analyzers to the Rescue

    I must confess.  I tend to do horribly at this sort of thing.  Despite having relatively good memory retention ability in theory, I have a critical Achilles Heel in this regard.  Specifically, I can only retain information that interests me.  And building up a massive arsenal of programming language "how-could-yous" for dueling purposes just doesn't interest me.  It doesn't solve any problem that I have.

    And, really, why should it?  Early in my career, I figured out the joy of static analyzers in pretty short order.  Just as the ubiquity of search engines means I don't need to memorize algorithms, the presence of static analyzers saves me from cognitively carrying around giant checklists of programming sins to avoid.  I rejoiced in this discovery.  Suddenly, I could solve interesting problems and trust the equivalent of programmer spell check to take care of the boring stuff.

    Oh, don't get me wrong.  After the analyzers slapped me, I internalized the lessons.  But I never bothered to go out of my way to do so.  I learned only in response to an actual, immediate problem.  "I don't like seeing warnings, so let me figure out the issue and subsequently avoid it."

    My Coding Provincialism

    This general modus operandi caused me to respond predictably when I first encountered the idea of globalization in language.  "Wait, so this helps when?  If someone theoretically deploys code to some other country?  And, then, they might see dates printed in a way that seems strange to them?  Huh."

    For many years, this solved no actual problem that I had.  Early in my career, I wrote software that people deployed in the US.  Much of it had no connectivity functionality.  Heck, a lot of it didn't even have a user interface.  Worst case, I might later have to realize that some log file's time stamps happened in Mountain Time or something.

    Globalization solved no problem that I had.  So when I heard rumblings about the "best practice," I generally paid no heed.  And, truth be told, nobody suffered.  With the software I wrote for many years, this would have constituted a premature optimization.

    But it nevertheless instilled in me a provincialism regarding code.

    A Dose of Reality

    I've spent my career as a polyglot.  And so at one point, I switched jobs, and it took me from writing Java-based web apps to a desktop app using C# and WPF.  This WPF app happened to have worldwide distribution.  And, when I say worldwide, I mean just about every country in the world.

    Suddenly, globalization went from "premature optimization" to "development table stakes."  And the learning curve became steep.  We didn't just need to account for the fact that people might want to see dates where the day, rather than the month, came first.  The GUI needed translation into dozens of languages as a menu setting.  This included languages with text read from right to left.

    How did I deal with this?  At the time, I don't recall having the benefit of a static analyzer that helped in this regard.  FXCop may have provided some relief, but I don't recall one way or the other.  Instead, I found myself needing to study and laboriously create mental checklists.  This "best practice" knowledge hoarding suddenly solved an immediate problem.  So, I did it.

    CodeIt.Right's Globalization Features

    Years have passed since then.  I've had several jobs since then, and, as a solo consultant, I've had dozens of clients and gigs.  I've lost my once encyclopedic knowledge of globalization concerns.  That happened because -- you guessed it -- it no longer solves an immediate problem that I have.

    Oh, I'd probably do better with it now than I did in the past.  But I'd still have to re-familiarize myself with the particulars and study up once again in order to get it right, should  the need arise.  Except, these days, I could enlist some help.  CodeIt.Right, installed on my machine, will give me the heads up I didn't have those years ago.  It has a number of globalization concerns built right in.  Specifically, it will remind you about the following concerns.  I'll just list them here, saving detailed explanations for a future "CodeIt.Right Rules, Explained" post.

    • Specify culture info
    • Specify string comparison (for culture)
    • Do not pass literals as localized parameters
    • Normalize strings to uppercase
    • Do not hard code locale specific strings
    • Use ordinal string comparison
    • Specify marshaling for PInvoke string arguments
    • Set locale for data types

    That provides an excellent head start on getting savvy with globalization.

    The Takeaway

    Throughout the post, I've talked about my tendency not to bother with things that don't solve immediate problems for me.  I realize philosophical differences in approach exist, but I stand by this practice to this day.  And I don't say this only because of time savings and avoiding premature optimization.  Storing up an arsenal of specific "best practices" in your head threatens to entrench you in your ways and to establish an approach of "that's just how you do it."

    And yet, not doing this can lead to making rookie mistakes and later repeating them.  But, for me, that's where automated tooling enters the picture.  I understand the globalization problem in theory.  That I have not forgotten.  And I can use a tool like CodeIt.Right to bridge the gap between theory and specifics in short order, creating just-in-time solutions to problems that I have.

    So to conclude the post, I would offer the following in takeaway.  Stop memorizing all of the little things you need to check for at the method level in coding. Let tooling do that for you, so that you can keep big picture ideas in your head.  I'd say, "don't lose sight of the forest for the trees," but with tooling, you can see the forest and the trees.

    Learn more how CodeIt.Right can help you automate code reviews, improve your code quality, and ensure your code is globalization ready.

    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

  • Manual Code Review Anti-Patterns

    Today, I'd like to offer a somewhat lighthearted treatment to a serious topic.  I generally find that this tends to offer catharsis to the frustrated.  And the topic of code review tends to lead to lots of frustration.

    When talking about code review, I always make sure to offer a specific distinction.  We can divide code reviews into two mutually exclusive buckets: automated and manual.  At first, this distinction might sound strange.  Most readers probably think of code reviews as activities with exclusively human actors.  But I tend to disagree.  Any static analyzer (including the compiler) offers feedback.  And some tools, like CodeIt.Right, specifically regard their suggestions and automated fixes as an automation of the code review process.

    I would argue that automated code review should definitely factor into your code review strategy.  It takes the simple things out of the equation and lets the humans involved focus on more complex, nuanced topics.  That said, I want to ignore the idea of automated review for the rest of the post.  Instead, I'll talk exclusively about manual code reviews and, more specifically, where they tend to get ugly.

    You should absolutely do manual code reviews.  Full stop.  But you should also know that they can easily go wrong and devolved into useless or even toxic activities.  To make them effective, you need to exercise vigilance with them.  And, toward that end, I'll talk about some manual code review anti-patterns.

    The Gauntlet

    First up, let's talk about a style of review that probably inspires the most disgust among former participants.  Here, I'm talking about what I call "the gauntlet."

    In this style of code review, the person submitting for review comes to a room with a number of self-important, hyper-critical peers.  Of course, they might not view themselves as peers.  Instead, they probably imagine themselves as a panel of judges for some reality show.

    From this 'lofty' perch, they attack the reviewee's code with a malevolent glee.  They adopt a derisive tone and administer the third degree.  And, frankly, they crush the spirit of anyone subject to this process, leaving low morale and resentment in their wake.

    The Marathon

    Next, consider a less awful, but not effective style of code review.  This one I call "the marathon."  I bet you can predict what I mean by this.

    In the marathon code review, the participants sit in some conference room for hours.  It starts out as an enthusiastic enough affair, but as time passes, people's energy wanes.  Nevertheless, it goes on because of an edict that all code needs review and because everyone waited until the 11th hour.  And predictably, things get less careless as time goes on and people space out.

    Marathon code reviews eventually reach a point where you might as well not bother.

    The Scattershot Review

    Scattershot reviews tend to occur in organizations without much rigor around the code review process.  Perhaps their process does not officially formally include code review.  Or, maybe, it offers on more specifics than "do it."

    With a scattershot review process, the reviewer demonstrates no consistency or predictability in the evaluation.  One day he might suggest eliminating global variables, and on another day, he might advocate for them.  Or, perhaps the variance occurs depending on reviewer.  Whatever the specifics, you can rest assured you'll never receive the same feedback twice.

    This approach to code review can cause some annoyance and resentment.  But morale issues typically take a backseat to simple ineffectiveness and churn in approach.

    The Exam

    Some of these can certainly coincide.  In fact, some of them will likely coincide.  So it goes with "the exam" and "the gauntlet."  But while the gauntlet focuses mostly on the process of the review, the exam focuses on the outcome.

    Exam code reviews occur when the parlance around what happens at the end involves "pass or fail."  If you hear people talking about "failing" a code review, you have an exam on your hands.

    Code review should involve a second set of eyes on something to improve it.  For instance, imagine that you wrote a presentation or a whitepaper.  You might ask someone to look it over and proofread it to help you improve it.  If they found a typo, they wouldn't proclaim that you had "failed."  They'd just offer the feedback.

    Treating code reviews as exams generally hurts morale and causes the team to lose out on the collaborative dynamic.

    The Soliloquy

    The review style I call "the soliloquy" involves paying lip service to the entire process.  In literature, characters offer soliloquies when they speak their thoughts aloud regardless of anyone hearing them.  So it goes with code review styles as well.

    To understand what I mean, think of times in the past where you've emailed someone and asked them to look at a commit.  Five minutes later, they send back a quick, "looks good."  Did they really review it?  Really?  You have a soliloquy when you find yourself coding into the vacuum like this.

    The downside here should be obvious.  If people spare time for only a cursory glance, you aren't really conducting code reviews.

    The Alpha Dog

    Again, you might find an "alpha dog" in some of these other sorts of reviews.  I'm looking at you, gauntlet and exam.  With an alpha dog code review, you have a situation where a particularly dominant senior developer rules the roost with the team.  In that sense, the title refers both to the person and to the style of review.

    In a team with a clear alpha dog, that person rules the codebase with an iron fist.  Thus the code review becomes an exercise in appeasing the alpha dog.  If he is present, this just results in him administering a gauntlet.  But, even absent, the review goes according to what he may or may not like.

    This tends to lead team members to a condition known as "learned helplessness," wherein they cease bothering to make decisions without the alpha dog.  Obviously, this stunts their career development, but it also has a pragmatic toll for the team in the short term.  This scales terribly.

    The Weeds

    Last up, I'll offer a review issue that I'll call "the weeds."  This can happen in the most well meaning of situations, particularly with folks that love their craft.  Simply put, they get "into the weeds."

    What I mean with this colloquialism is that they bogged down in details at the expense of the bigger picture.  Obviously, an exacting alpha dog can drag things into the weeds, but so can anyone.  They might wind up with a lengthy digression about some arcane language point, of interest to all parties, but not critical to shipping software.  And typically, this happens with things that you ought to make matters of procedures, or even to address with your automated code reviews.

    The biggest issue with a "weeds" code review arises from the poor use of time.  It causes things to get skipped, or else it turns reviews into marathons.

    Getting it Right

    How to get code reviews right could easily occupy multiple posts.  But I'll close by giving a very broad philosophical outlook on how to approach it.

    First of all, make sure that you get clarity up front around code review goals, criteria, and conduct.  This helps to stop anti-patterns wherein the review gets off track or bogged down.  It also prevents soliloquies and somewhat mutes bad behavior.  But, beyond that, look at code reviews as collaborative, voluntary sessions where peers try to improve the general codebase.  Some of those peers may have more or less experience, but everyone's opinion matters, and it's just that -- an opinion for the author to take under advisement.

    While you might cringe at the notion that someone less experienced might leave something bad in the codebase, trust me.  The damage you do by allowing these anti-patterns to continue in the name of "getting it right" will be far worse.

    Learn more how CodeIt.Right can help you automate code reviews 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

  • CodeIt.Right Rules Explained, Part 4

    Today, I'll do another installment of the CodeIt.Right Rules, Explained series.  I have now made four such posts in this series.  And, as always, I'll start off by citing my two personal rules about static analysis guidance.

    • Never implement a suggested fix without knowing what makes it a fix.
    • Never ignore a suggested fix without understanding what makes it a fix.

    It may seem as though I'm playing rhetorical games here.  After all, I could simply say, "learn the reasoning behind all suggested fixes."  But I want to underscore the decision you face when confronted with static analysis feedback.  In all cases, you must actively choose to ignore the feedback or address it.  And for both options, you need to understand the logic behind the suggestion.

    In that spirit, I'm going to offer up explanations for three more CodeIt.Right rules today.

    Type that contains only static members should be sealed

    Let's start here with a quick example.  I think this picture will suffice for some number of words, if not necessarily one thousand.


    Here, I've laid a tiny seed for a Swiss Army Knife, "utils" class.  Presumably, I will continue to dump any method I think might help me with Linq into this class.  But for now, it contains only a single method to make things easy to understand.  (As an aside, I discourage "utils" classes as a practice.  I'm using this example because everyone reading has most assuredly seen one of these things at some point.)

    When you run CodeIt.Right analysis on this code, you will find yourself confronted with a design issue.  Specifically, "types that contain only static members should be sealed."

    You probably won't have a hard time discerning how to remedy the situation.  Adding the "sealed" modifier to the class will do the trick.  But why does CodeIt.Right object?

    The Microsoft guidelines contain a bit more information.  They briefly explain that static analyzers make an inference about your design intent, and that you can better communicate that intent by using the "sealed" keyword.  But let's unpack that a bit.

    When you write a class that has nothing but static members, such as a static utils class, you create something with no instantiation logic and no state.  In other words, you could instantiate "a LinqUtils," but you couldn't do anything with it.  Presumably, you do not intend that people use the class in that way.

    But what about other ways of interacting with the class, such as via inheritance?  Again, you could create a LinqUtilsChild that inherited from LinqUtils, but to what end?  Polymorphism requires instance members, and non exist here.  The inheriting class would inherit absolutely nothing from its parent, making the inheritance awkward at best.

    Thus the intent of the rule.  You can think of it telling you the following.  "You're obviously not planning to let people use inheritance with you, so don't even leave that door open for them to possibly make a mistake."

    So when you find yourself confronted with this warning, you have a simple bit of consideration.  Do you intend to have instance behavior?  If so, add that behavior and the warning goes away.  If not, simply mark the class sealed.

    Async methods should have async suffix

    Next up, let's consider a rule in the naming category.  Specifically, when you name an async method with suffixing "async" on its name, you see the warning.  Microsoft declares this succinctly in their guidelines.

    By convention, you append "Async" to the names of methods that have an async modifier.

    So, CodeIt.Right simply tells us that we've run afoul of this convention.  But, again, let's dive into the reasoning behind this rule.

    When Microsoft introduced this programming paradigm, they did so in a non-breaking release.  This caused something of a conundrum for them because of a perfectly understandable language rule stating that method overloads cannot vary only by a return type.  To take advantage of the new language feature, users would need to offer the new, async methods, and also backward compatibility with existing method calls.  This put them in the position of needing to give the new, async methods different names.  And so Microsoft offered guidance on a convention for doing so.

    I'd like to make a call-out here with regard to my two rules at the top of each post.  This convention came about because of expediency and now sticks around for convention's sake.  But it may bother you that you're asked to bake a keyword into the name of a method.  This might trouble you in the same way that a method called "GetCustomerNumberString()" might bother you.  In other words, while I don't advise you go against convention, I will say that not all warnings are created equally.

    Always define a global error handler

    With this particular advice, we dive into warnings specific to ASP.  When you see this warning, it concerns the Global.asax file.  To understand a bit more about that, you can read this Stack Overflow question.  In short, Global.asax allows you to define responses to "system level" in a single place.

    CodeIt.Right is telling you to define just such an event -- specifically one in response to the "Application_Error" event.  This event occurs whenever an exception bubbles all the way up without being trapped anywhere by your code somewhere.  And, that's a perfectly reasonable state of affairs -- your code won't trap every possible exception.

    CodeIt.Right wants you to define a default behavior on application errors.  This could mean something as simple as redirecting to a page that says, "oops, sorry about that."  Or, it could entail all sorts of robust, diagnostic information.  The important thing is that you define it and that it be consistent.  You certainly don't want to learn from your users what your own application does in response to an error.

    So spent a bit of time defining your global error handling behavior.  By all means, trap and handle exceptions as close to the source as you can.  But always make sure to have a backup plan.

    Until Next Time

    In this post, I ran the gamut across concerns.  I touched on an object-oriented design concern.  Then, I went into a naming consideration involving async, and, finally, I talked specifically about ASP programming considerations.

    I don't have a particular algorithm for the order in which I cover these subjects.  But, I like the way this shook out.  It goes to show you that CodeIt.Right covers a lot of ground, across a lot of different landscapes of the .NET world.

    Learn more how CodeIt.Right can help you automate code reviews 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

  • Released: GhostDoc v5.5

    GhostDoc version 5.5 delivers compatibility with VS2017 RTM as well as a number of fixes:

    • VS2017 RTM support
    • GhostDoc is now also available as VSIX for VS2017
    • Documentation Hints no longer visible in the Debug mode
    • Fixed issue wrapping lines within the <value></value> tag
    • In the Offline Activation Preview - the fields are now auto-selected on focus/click for easy copying
    • GhostDoc is no longer adding extra line when re-documenting header in VB
    • GhostDoc is no longer appending generated XML comments to the existing comment when using auto-generated properties in VB

    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

  • Automation and the Art of Software Maintenance

    I have long since cast my lot with the software industry.  But, if I were going to make a commercial to convince others to follow suit, I can imagine what it would look like.  I'd probably feature cool-looking, clear whiteboards, engaged people, and frenetic design of the future.  And a robot or two.  Come help us build the technology of tomorrow.

    Of course, you might later accuse me of bait and switch.  You entered a bootcamp, ready to build the technology of tomorrow.  Three years later, you found yourself on safari in a legacy code jungle, trying to wrangle some SharePoint plugin.  Erik, you lied to me.

    So, let me inoculate myself against that particular accusation.  With a career in software, you will certainly get to work on some cool things.  But you will also find yourself doing the decidedly less glamorous task of software maintenance.  You may as well prepare yourself for that now.

    The Conceptual Difference: Build vs Maintain

    From the software developer's perspective, this distinction might evoke various contrasts.  Fun versus boring.  Satisfying versus annoying.  New problem versus solved problem.  My stuff versus that of some guy named Steve that apparently worked here 8 years ago.  You get the idea.

    But let's zoom out a bit.  For a broader perspective, consider the difference as it pertains to a business.

    blog-automation-software-maintenance-1Build mode (green field) means a push toward new capability.  Usually, the business will regard construction of this capability as a project with a calculated return on investment (ROI).  To put it more plainly, "we're going to spend $500,000 building this thing that we expect to make/save us $1.5 million by next year."

    Maintenance mode, on the other hand, presents the business with a cost center.  They've now made their investment and (at least partially) realized return on it.  The maintenance team just hangs around to prevent backslides.  For instance, should maintenance problems crop up, you may lose customers or efficiency.

    Plan of Attack: Build vs Maintain

    Because the business regards these activities differently, it will attack them differently.  And, while I can't speak to every conceivable situation, my consulting work has shown me wide variety.  So I can speak to general trends.

    In green field mode, the business tends to regard the work as an investment.  So, while management might dislike overruns and unexpected costs, they will tend to tolerate them more.  Commonly, you see a "this will pay off later" mentality.

    On the maintenance side of things, you tend to see far less forgiveness.  Certainly, all parties forgive unexpected problems a lot less easily.  They view all of it as a burden.

    This difference in attitude translates to the planning as well.  Green field projects justifiably command full time people for the duration of the project.  Maintenance mode tends to get you familiar with the curious term "half of a person."  By this, I mean you hear things like "we're done with the Sigma project, but someone needs to keep the lights on.  That'll be half of Alice."  The business grudgingly allocates part time duty to maintenance tasks.

    Why?  Well, maintenance tends to arise out of reactive scenarios.

    Reactive Mode and the Value of Automation

    Maintenance mode in software will have some planned activities, particularly if it needs scheduled maintenance.  But most maintenance programmers find themselves in a reactive, "wait and see" kind of situation.  They have little to do on the project in question until an outage happens, someone discovers a bug, or a customer requests a new feature.  Then, they spring into action.

    Business folks tend to hate this sort of situation.  After all, you need to plan for this stuff, but you might have someone sitting around doing nothing.  It is from this fundamental conundrum that "half people" and "quarter people" arise.  Maintenance programmers usually have other stuff to juggle along with maintaining "Sigma."

    You should automate this stuff during green field time, when management is willing to invest. If you tell them it means less maintenance cost, they'll probably bite.

    Because of this double duty, the business doubles down on pressure to minimize maintenance.  After all, not only does it create cost, but it takes the people away from other, profit-driven things that they could otherwise do.

    So how do we, as programmers, and we, as software shops, best deal with this?  We make maintenance as turnkey as possible by automating as much as possible.  Oh, and you should automate this stuff during green field time, when management is willing to invest.  If you tell them it means less maintenance cost, they'll probably bite.

    Automate the Test Suite

    First up for automation candidates, think of the codebase's test suite.  Hopefully, you've followed my advice and built this during green field mode.  But, if not, it's never too late to start.

    Think of how time consuming a job QA has.  If manually running the software and conducting experiments constitutes the entirety of your test strategy, you'll find yourself hosed at maintenance time.  With "half a person" allocated, no one has time for that.  Without an automated suite, then, testing falls by the wayside, making your changes to a production system even more risky.

    You need to automate a robust test suite that lets you know if you have broken anything.  This becomes even more critical when you consider that most maintenance programmers haven't touched the code they modify in a long time, if ever.

    Automate Code Reviews

    If I were to pick a one-two punch for code quality, that would involve unit tests and code review.  Therefore, just as you should automate your test suite, you should automate your code review as well.

    If you think testing goes by the wayside in an under-staffed, cost-center model, you can forget about peer review altogether.  During the course of my travels, I've rarely seen code review continue into maintenance mode, except in regulated industries.

    Automated code review tools exist, and they don't require even "half a person."  An automated code review tool serves its role without consuming bandwidth.  And, it provides maintenance programmers operating in high risk scenarios with a modicum of comfort and safety net.

    Automate Production Monitoring

    For my last maintenance mode automation tip of the post, I'll suggest that you automate production monitoring capabilities.  This covers a fair bit of ground, so I'll generalize by saying these include anything that keeps your finger on the pulse of your system's production behavior.

    You have logging, no doubt, but do you monitor the logs?  Do you keep track of system outages and system load?  If you roll software to production, do you have a system of checks in place to know if something smells fishy?

    You want to make the answer to these questions, "yes."  And you want to make the answer "yes" without you needing to go in and manually check.  Automate various means of monitoring your production software and providing yourself with alerts.  This will reduced maintenance costs across the board.

    Automate Anything You Can

    I've listed some automation examples that come to mind as the most critical, based on my experience.  But, really, you should automate anything around the maintenance process that you can.

    Now, you might think to yourself, "we're programmers, we should automate everything."  Well, that subject could make for a whole post in and of itself, but I'll speak briefly to the distinction.  Build mode usually involves creating something from nothing on a large scale.  While you can automate the scaffolding around this activity, you'll struggle to automate a significant amount of the process.

    But that ratio gets much better during maintenance time.  So the cost center nature of maintenance, combined with the higher possible automation percentage, makes it a rich target.  Indeed, I would argue that strategic automation defines the art of maintenance.

    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.

    Related resources

    Learn more how CodeIt.Right can help you automate code reviews 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

  • Add Custom Content to Your Help Documentation

    For the last several years, I've made more and more of my living via entrepreneurial pursuits.  I started my career as a software developer and then worked my way along that career path before leaving fulltime employment to do my own thing.  These days, I consult, but I also make training content, write books, and offer productized services.

    When you start to sell things yourself, you come to appreciate the value of marketing.  As a techie, this feels a little weird to say, but here we are.  When you have something of value to offer, marketing helps you make interested parties aware of your offer.  I think you'd like this and find it worth your money, if you gave it a shot.

    In pursuit of marketing, you can use all manner of techniques.  But today, I'll focus on a subtle one that involves generating a good reputation with those who do buy your products.  I want to talk about making good documentation.

    The Marketing Importance of Documentation

    This probably seems an odd choice for a marketing discussion.  After all, most of us think of marketing as what we do before a purchase to convince customers to make that purchase.  But repeat business from customer loyalty counts for a lot.  Your loyal customers provide recurring revenue and, if they love their experience, they may evangelize for your brand.

    Providing really great documentation makes an incredible difference for your product.  I say this because it can mean the difference between frustration and quick, easy wins for your user base.  And, from a marketing perspective, which do you think makes them more likely to evangelize?  Put yourself in their shoes.  Would you recommend something hard to figure out?

    For a product with software developers as an end user, software documentation can really go a long way.  And with something like GhostDoc's "build help documentation" feature, you can notch this victory quite easily.  But the fact that you can generate that documentation isn't what I want to talk about today, specifically.

    Instead, I want to talk about going the extra mile by customizing it.

    Introducing "Conceptual Content"

    You can easily generate documentation for your API with the click of a button.  But you can also do a lot more.

    GhostDoc Enterprise features something called "Conceptual Content."  Basically, it allows you to customize and add on to what the engine generates using your code and XML doc comments.  This comes in handy in ways limited only by your imagination, but here are some ideas.

    • A welcome page.
    • A support page.
    • A "what's new" page.
    • Including a EULA/license.
    • Custom branding.

    You probably get the idea.  If you already look to provide documentation for your users, you no doubt have some good additional thoughts for what they might value.  Today, I'm going to show you the simplest way to get going with conceptual content so that you can execute on these ideas of yours.

    How It Works at a High Level

    For GhostDoc to work its documentation-generating magic, it creates a file in your solution directory named after your solution.  For instance, with my ChessTDD solution, it generates a file called "ChessTDD.sln.GhostDoc.xml."  If you crack open this file, you will see settings mirroring the ones you select in Visual Studio when using GhostDoc's "Build Help Documentation."

    To get this going, we face the task of basically telling this file about custom content that we will create.  First, close out of Visual Studio, and let's get to work hacking at this thing a bit.  We're going to add a simple, text-based welcome page to the standard help documentation.  To do this, we need the following things.

    • Modifications to the GhostDoc XML file.
    • The addition of a "content" file describing our custom content,
    • Addition of a "content" folder containing the AML files that make up the actual, custom pages.

    Let's get started.

    The Nuts and Bolts

    First, open up the main GhostDoc XML file and look for the "ConceptualContent" section.  It looks like this.

    <ConceptualContent> <ContentLayout /> <MediaContent /> </ConceptualContent>

    In essence, this says, "no conceptual content here."  We need to change that.  So, replace the empty ContentLayout entry with this (substituting the name of your solution for "ChessTDD" if you want to follow along with your own instead of my ChessTDD code.)

    <ContentLayout file="ChessTDD.content" folder="Content\" />

    Next up, you need to create the file you just told it about, ChessTDD.content.  This file goes in the same directory as your solution and looks like this.

    <?xml version="1.0"
    encoding="utf-8"?> <Topics> <Topic id="4684cc2f-3179-4871-b7a4-ad69f0f260a3" visible="True" isDefault="true" title="Welcome"> <HelpKeywords> <HelpKeyword index="K" term="Welcome" /> </HelpKeywords> </Topic> </Topics>

    For the ID, I simply generated a GUI using this site.  This ID simply needs to be unique, and to match the next file that we'll create.  Next up, create the folder you told ContentLayout about called, "Content."  Then add the file Welcome.aml to that folder, with the following text.

    <?xml version="1.0"
    encoding="utf-8"?> <topic id="4684cc2f-3179-4871-b7a4-ad69f0f260a3" revisionNumber="1"> <developerConceptualDocument xmlns="" xmlns:xlink=""> <introduction> <para>Welcome
    to our help section!</para> </introduction> </developerConceptualDocument> </topic>

    Notice that we use the same GUID here as in the content file.  We do this in order to link the two.

    Let's Give it a Whirl

    With your marked up Ghost Doc XML file, the new content file, and the new Content folder and welcome AML file, you can now re-launch Visual Studio.  Open the solution and navigate through GhostDoc to generate the help documentation CHM file.


    There you have it.  Now you can quickly add a page to the automatically generated help documentation.

    Keep in mind that I did the absolute, dead simplest possible thing I could do for demonstration purposes.  You can do much more.  For example:

    • Adding images/media to the pages.
    • Have cross-links in there for reference.
    • Add snippets and examples.
    • Build lists and tables.

    As I said earlier, you'll no doubt think of all manner of things to please your user base with this documentation.  I suggest getting in there, making it your own, and leaving a nice, personal touch on things for them.  When it comes to providing a good user experience, a little can go a long way.

    Related resources

    Learn how GhostDoc can help to simplify your XML Comments, produce and maintain quality help documentation.

    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

  • CodeIt.Right Rules Explained, Part 3

    In what has become a series of posts, I have been explaining some CodeIt.Right rules in depth.  As with the last post in the series, I'll start off by citing two rules that I, personally, follow when it comes to static code analysis.

    • Never implement a suggested fix without knowing what makes it a fix.
    • Never ignore a suggested fix without understanding what makes it a fix.

    It may seem as though I'm playing rhetorical games here.  After all, I could simply say, "learn the reasoning behind all suggested fixes."  But I want to underscore the decision you face when confronted with static analysis feedback.  In all cases, you must actively choose to ignore the feedback or address it.  And for both options, you need to understand the logic behind the suggestion.

    In that spirit, I'm going to offer up explanations for three more CodeIt.Right rules today.

    Use Constants Where Appropriate

    First up, let's consider the admonition to "use constants where appropriate."  Consider this code that I lifted from a Github project I worked on once.


    I received this warning on the first two lines of code for this class.  Specifically, CodeIt.Right objects to my usage of static readonly string. If I let CodeIt.Right fix the issue for me, I wind up with the following code.


    Now, CodeIt.Right seems happy.  So, what gives?  Why does this matter?

    I'll offer you the release notes of the version where CodeIt.Right introduced this rule.  If you look at the parenthetical next to the rule, you will see "performance."  This preference has something to do with code performance.  So, let's get specific.

    When you declare a variable using const or static readonly, think in terms of magic values and their elimination.  For instance, imagine my UserAgentKey value.  Why do you think I declare that the way I did?  I did it to name that string, rather than using it inline as a "magic" string. 

    As a maintenance programmer, how frustrating do you find stumbling across lines of code like, "if(x == 299)"?  "What is 299, and why do we care?!"

    So you introduce a variable (or, preferably, a constant) to document your intent.  In the made-up hypothetical, you might then have "if(x == MaximumCountBeforeRetry)".  Now you can easily understand what the value means.

    Either way of declaring this (constant or static, readonly field) serves the replacement purpose.  In both cases, I replace a magic value with a more readable, named one.  But in the case of static readonly, I replace it with a variable, and in the case of const, I replace it with, well, a const.

    From a performance perspective, this matters.  You can think of a declaration of const as simply hard-coding a value, but without the magic.  So, when I switch to const, in my declaration, the compiler replaces every version of UserAgentKey with the string literal "user-agent".  After compilation, you can't tell whether I used a const or just hard-coded it everywhere.

    But with a static readonly declaration, it remains a variable, even when you use it like a constant.  It thus incurs the relative overhead penalty of performing a variable lookup at runtime.  For this reason, CodeIt.Right steers you toward considering making this a constant.

    Parameter Names Should Match Base Declaration

    For the next rule, let's return to the Github scraper project from the last example.  I'll show you two snippets of code.  The first comes from an interface definition and the second from a class implementing that interface.  Pay specific attention to the method, GetRepoSearchResults.



    If you take a look at the parameter names, it probably won't surprise you to see that they do not match.  Therein lies the problem that CodeIt.Right has with my code.  It wants the implementing class to match the interface definition (i.e. the "base").  But why?

    In this case, we have a fairly simple answer.  Having different names for the conceptually same method creates confusion. 

    Specifically, maintainers will struggle to understand whether you meant to override or overload the method.  In our mind's eyes, identical method signatures signals polymorphic approaches, while same name, different parameters signals overload.  In a sense, changing the name of a variable fakes maintenance programmers out.

    Do Not Declare Externally Visible Instance Fields

    I don't believe we need a screenshot for this one.  Consider the following trivial code snippet.

    public class SomeClass
    { public string _someVariable;

    This warning says, "don't do that."  More specifically, don't declare an instance field with external (to the type) visibility.  The question is, "why not?"

    If you check out the Microsoft guidance on the subject, they explain that, the "use of a field should be as an implementation detail."  In other words, they contend that you violate encapsulation by exposing fields.  Instead, they say, you should expose this via a property (which simply offers syntactic sugar over a method).

    Instead of continuing with abstract concepts, I'll offer a concrete example.  Imagine that you want to model a family and you declare an integer field called _numberOfChildren. That works fine initially, but eventually you encounter the conceptually weird edge case where someone tries to define a family with -1 children.  With an integer field, you can technically do this, but you want to prevent that from happening.

    With clients of your class directly accessing and setting this field, you wind up having to go install this guard logic literally everywhere your clients interact with the field.  But had you hidden the field behind a property, you could simply add logic to the property setter wherein you throw an exception on an attempt to set a negative value.

    This rule attempts to help you future-proof your code and follow good OO practice.

    Until Next Time

    Somewhat by coincidence, this post focused heavily on the C# flavor of object-oriented programming.  We looked at constants versus field access, but then focused on polymorphism and encapsulation.

    I mention this because I find it interesting to see where static analyzers take you.  Follow along for the rest of the series and, hopefully, you'll learn various useful nuggets about the language you use.

    Learn more how CodeIt.Right can help you automate code reviews 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

  • GhostDoc Says the Damndest Things

    Editorial note: most of the GhostDoc bloopers below are a history, but they provide for a good laugh. We encourage you to share the GhostDoc goofs you have encountered – they are great for entertainment as well as give us a chance to improve the product.

    Some years ago, I was doing work for some client or another.  Honestly, I have no recollections of specifics with the exception of a preference for exhaustive commenting.  Every class, every method, every property, and every field.

    Of course, I didn't learn this at first.  I didn't even learn it in a reasonable time frame.  Instead, I learned it close to handover time.  And so things got a little desperate.

    Enter GhostDoc, My Salvation

    Now, depending on your perspective, you might scold me for not diligently commenting all along.  I will offer the explanation that the code had no public component and no intended APIs or extensions.  It also required no "why" types of explanations; this was simple stuff.

    The client cited policy.  "We comment everything, and we're taking over this code, so we want you to do the same."  Okie Dokie.

    Now, I knew that in a world of code generation and T4 templates, someone must have invented a tool that would generate some sort of comments or another.  At the time, a quick Google search brought me to a saving grace: the free tool GhostDoc.

    While it did not allow me to carpet bomb my code with comments in a single click (and understandably so), it did allow me to do it for entire files at a time.  Good enough.  I paid my non-commenting penance by spending an hour or so commenting this way.

    And do you know what?  It generated pretty respectable comments.  I recall feeling impressed because I expected empty template comments.  Instead, GhostDoc figured out how to string some verbs and nouns together.

    But It's Not All Roses

    Let me get specific about capabilities and limitations.  Had I tried to generate documentation for my Chess TDD codebases's MovePiece method, GhostDoc would have treated me to this comment.

    /// <summary> /// Moves
    the piece. /// </summary> /// <param
    name="origin">The origin.</param> /// <param
    name="destination">The destination.</param> public void MovePiece(BoardCoordinate
    origin, BoardCoordinate destination) { VerifyCoordinatesOrThrow(origin, destination); var pieceToMove = GetPiece(origin);
    AddPiece(pieceToMove, destination); RemovePiece(origin); pieceToMove.HasMoved = true;
    ReconcileEnPassant(origin, destination, pieceToMove); }

    See what I mean?  I did a pretty good job with clear naming in this method, and GhostDoc rewarded me with a method header that stands on its own.  MovePiece() moves the piece.  Specifically, it moves the origin to the destination.  Not too shabby!

    But what about less intuitive naming structures?  Well, sometimes, things can get weird.

    Do you know there was a Visual Studio addon that generated comments from method names? I once inherited a project full of these.

    — Dan Abramov (@dan_abramov) December 15, 2016

    Yes, that's right.  The ubiquitous "main" method for a C# application "mains the args."

    What Else?

    Okay, that ought to furnish a chuckle.  But now that you see the issue, you can probably start to imagine all manner of ways to flummox the poor tool.  (As an aside, you can probably also understand why they want to force you to pay more attention to the generated comments than just saying "generate comments for the whole solution.")

    What do you think used to happen back then for a no-op method that you named "DoNothing?"  You'd get "Does the Nothing."  Good work on conjugation, but still missing the intent.  How about an event handler called "AfterInsert?"  That's right.  "Afters the Insert."  And "TaskComplete?"  "Tasks the completed."  Now, here's a tougher one: "OnClose."  You probably weren't expecting "Oncloses the instance."

    Of course, other idiomatic programming concerns also befuddled the tool in different ways.

    • ToModel() --> "Toes the model."
    • ToTitleCase() --> "Toes the title case."
    • ToComment() -> "Automatics the comment"
    • ForgetPassword() --> "Forgets password"
    • SignOut() --> "Signs the out"

    Or how about

    Historically, you could make GhostDoc generate some pretty hilarious comments.  This means that if you simply generated the comments and paid no further attention, you might look pretty absurd to someone auditing commit history.  Fortunately, my oversight of the generated comments saved me from that fate.

    Laugh at the Tool?

    So should you laugh at GhostDoc?  Well, sure.  These comments are funny, and everyone ought to have a sense of humor.

    But on a deeper level, no, not really.  Natural language processing presents a difficult problem.  Imagine yourself writing code to process class, method, and variable names.  At first, you might thing it easy.  But then you'd hit things like "ToString()" and "TaskComplete()."  As a human and programmer, you understand these nuances.  But how do you make your code do the same?

    Oh, sure, you can hard-code some overrides for unique situations.  But that will quickly become cumbersome.  As you can see, you have a hard problem on your hands.

    What You Can Do

    What should you do, then, as a user of GhostDoc?  Well, first and foremost, don't just mindlessly generate comments.  At the bare minimum, do what I did.  Mindlessly generate comments, but also look to make sure that they make sense, correcting any that don't.

    But, beyond that, use GhostDoc as a starting point for meaningful communication.  Generate XML doc comments only when doing so to communicate with someone, either via code comments or IntelliSense/help documentation.  And when you do that, understand that GhostDoc simply offers you an intelligent starting point.  The tool does not purport to replace you as a programmer or a communicator of your intent.  It just gets you started.

    Improving the Situation

    Of course, GhostDoc has improved over the years.  For instance, if I write a ToString() method and generate, it no longer offers me a "toes the string."  Instead, it does this.

    /// <summary> /// Returns
    a <see cref="System.String" /> that
    represents this instance. /// </summary> /// <returns>A <see
    cref="System.String" /> that represents this
    instance.</returns> public string ToString()
    { return "I'm
    a board.";

    Now, GhostDoc actually does something pretty sophisticated.  It figures out that ToString() has a special place in the language and adapts accordingly, explaining that place with a marked-up comment.

    Similarly, if you try to reproduce some of the shenanigans I detailed above, you will receive less obtuse results.  The people working on the GhostDoc codebase are constantly seeking to improve the quality of the generated comments, even if they only serve as a starting point.  But they could always use some help, so here is what I propose.

    Luckily, there is a Summary Override feature in GhostDoc, and you should use it to improve the future generated comments once you find a new blooper.

    Write in or comment with funny or weird things that you can get GhostDoc to produce when you generate documentation.  Seriously.  It'll give you, me, the readership, and the tool authors a good laugh.  But it will also bring deficiencies to their attention, allowing them to address, correct, and improve.  So go ahead.  What are your favorite GhostDoc bloopers?

    Learn more about how GhostDoc can help simplify your XML Comments, produce and maintain quality help documentation.

    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

  • You Can Use GhostDoc's Document This with JavaScript

    If you haven't lived in a techie cave the last 10 years, you've probably noticed JavaScript's rise to prominence.  Actually, forget prominence.  JavaScript has risen to command consideration as today's lingua franca of modern software development.

    I find it sort of surreal to contemplate that, given my own backstory.  Years (okay, almost 2 decades) ago, I cut my teeth with C and C++.  From there, I branched out to Java, C#, Visual Basic, PHP, and some others I'm probably forgetting.  Generally speaking, I came of age during the heyday of object oriented programming.

    Oh, sure I had awareness of other paradigms.  In college, I had dabbled with (at the time) the esoteric concept of functional programming.  And I supplemented "real" programming work with scripts as needed to get stuff done.  But object-oriented languages gave us the real engine that drove serious work.

    JavaScript fell into the "scripting" category for me, when I first encountered it, probably around 2001 or 2002.  It and something called VBScript competed for the crown of "how to do weird stuff in the browser, half-baked hacky languages."  JavaScript one that battle and cemented itself in my mind as "the thing to do when you want an alert box in the browser."

    Even as it has risen to prominence and inspired a generation of developers, I suppose I've never really shed my original baggage with it.  While I conceptually understand its role as "assembly language of the web," I have a hard time not seeing the language that was written in 10 days and named to deliberately confuse people.

    GhostDoc, Help, and IntelliSence

    I lead with all of this to help you understand the lens through which to read this post.  As a product of the strongly typed, object-oriented wave of programmers, my subconscious still regards JavaScript as something of an afterthought, its dominance notwithstanding.  And so when I see advances in the JavaScript world, I tend to think, "Oh, cool, you can do that with JavaScript too!"

    I'll come back to that shortly.  But first, I'd like to remind you of a prominent GhostDoc feature.  Specifically, I'm referring to the "Document This" capability.  With your cursor inside of a method or type, you can use this capability to generate instant, well-formatted, XML doc comments.  Thoroughly documented code sits just a "Ctrl-Shift-D" away.

    If you work with C# a lot and generate public APIs and/or help documentation, you will love this capability.  It doesn't absolve you of needing to add specific contest.  But it does give you a thorough base upon which to build.  For example, consider this method from my ChessTDD example codebase.

    /// <summary> /// Gets
    the moves from. /// </summary> /// <param
    name="startingLocation">The starting location.</param> /// <param
    name="boardSize">Size of the board.</param> /// <returns>IEnumerable&lt;BoardCoordinate&gt;.</returns> public override IEnumerable<BoardCoordinate> GetMovesFrom(BoardCoordinate
    startingLocation, int boardSize = Board.DefaultBoardSize)
    { var oneSquareAwayMoves = GetAllRadialMovesFrom(startingLocation, 1); return oneSquareAwayMoves.Where(bc => bc.IsCoordinateValidForBoardSize(boardSize));

    I took that un-commented method and used GhostDoc to generate this.  Now, I Should probably update the summary, but I really don't see any other deficiencies here.  It nails the parameter names, and it even escapes the generic return type for readability.

    It Works with JavaScript, Too

    Now, as I've said earlier, I don't really play much in the JavaScript world.  I generally focus on application code and server side stuff, delving into the realm of the client side browser only when necessary to get things done.  So you can imagine my reaction to learn that GhostDoc can do this with JavaScript too.  It can produce sophisticated XML doc comments that allow for use in generating help and with IntelliSence.

    Actually, if I really want to embarrass myself, I'll confess that my initial reaction was, "JavaScript code has IntelliSence?"  I think maybe I knew that, but I assumed that such a thing would offer little value in a dynamically typed language.  Shows what I know.  But then, once I got over that initial wave of ignorance, I thought, "cool!" at the idea that you could generate documentation for JavaScript.  I then wondered if well-documented JavaScript was more or less rare than well documented C#.  That jury has yet to come back, as far as I know.

    Let's Take a Look

    Let's take a look at what GhostDoc actually does here.  To demonstrate, I created a branch of my ChessTDD project, to which I added an ASP MVC front end.  This plopped some JavaScript right in my lap, in the form of the default files in the "Scripts" folder.  To see this in action, I popped open modernizr-2.6.2.js and found a method upon which to experiment.


    ShivMethods sounded... interesting, in a prison yard sort of way.  As a publicly consumable library, it already has documentation.  And, as I learned by playing around, that documentation already gets picked up by IntelliSense.  But I figured I'd see what happened by using GhostDoc anyway, for comparison's sake.

    So I lazily put my cursor randomly inside the method and fired away with a Ctrl-Shift-D.  Check it out.


    As you can see, GhostDoc puts the comment inside of the method and behaves largely as it would with C#.  In case you're wondering about the stylistic difference, GhostDoc does this because it's the more Microsoft-preferred way.  To underscore that, look what happens now when we consume this method with IntelliSense.


    As you can see, IntelliSense gives preference to the comments generated by GhostDoc.

    The Takeaway

    What's my main point here?  I simply wanted to share that you can use GhostDoc for JavaScript just as you can with C# or VB.

    Forget about my crotchety ways and biases.  Your JavaScript/client-side code is every bit as important as what you write anywhere else.  You should treat it as such when documenting it, creating help for it, and making sure users know how to consume your libraries.  So make sure you've got Ctrl-Shift-D at the ready when using Visual Studio, regardless of where the code gets executed.

    Learn more about how GhostDoc can help simplify your XML Comments, produce and maintain quality help documentation.

    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

More Posts Next page »

This Blog


Home |  Products |  Services |  Download |  Purchase |  Support |  Community |  About Us |