Software Quality Blog - SubMain Software - Code Quality Tools, Automated Code Review and Refactoring

Different tool vendors can help you automate API documentation.

How Do You Handle API Documentation?

October 17, 2017Erik DietrichArticles, Documentation, ErikDietrich, GhostDocNo Comments

The subject of API documentation reveals a fascinating property of the software development industry that makes it truly unique. When you think of a product, you think of something polished and ready to ship. That’s true of software and also of the broader world in general. But only in software can you crack the product open to reveal its internals and then ship that as well, with a different purpose.

When you expose an API, this is exactly what you do. Take an offering like, say, the iconic Trello. On the surface, you have a lightweight kanban utility with a nice user experience. But you also have an underlying platform for developers to use. Through the Trello API, developers can build their own functionality to extend and enhance the offering, creating a win for everyone. Developers win because they can do cool things. Trello wins because it generates more interest in their offering. End users win because they have a richer set of functionality at their disposal.

Of course, extensible software is hardly new. But these days, it’s becoming more and more the norm. And it’s also something that companies plan for from the get-go, rather than scrambling to bolt on at a later date. So it’s important to treat APIs as first-class citizens, conceiving of them as actual products and doing things like, say, shipping API documentation.

What is API Documentation?

Most people reading can probably infer what this means, but it’s worth being explicit before proceeding. API documentation is a standalone set of deliverables that you offer to clients of an API. And for the sake of thoroughness, “API” stands for “application programmer interface.” So you’re documenting how programmers should interact with your platform through code.

At a bare minimum, your API documentation should include information about setting up to use the API. It should also describe the different function calls, parameters, and return values. Sophisticated API documentation will also include examples, caveats, gotchas, and any other useful tidbits that might make life easier for developers.

Is API Documentation Really Necessary?

Could you ship your product and API with no documentation? Sure. Could this work out for you? Probably, somewhere, somehow. But I wouldn’t call it a good idea in most cases.

The entire point of an API is to open up your product for extension. You invite developers to come in, poke around, and get comfortable. You want them to use your product, extend it, and build a community around it.

Without API documentation, you’re not really rolling out the welcome mat. Instead, you’re leaving it up to them to learn by trial and error what to do. The probable result? They’ll try, get frustrated, and leave. Or perhaps they won’t try at all, viewing it as a waste of time. Either way, they’ll go looking for your competitors who, presumably, have nice API documentation.

So let’s assume that, all things being equal, API documentation is desirable. What are some strategies that shops have for their API documentation?

API Documentation Via Oral Tradition

While not doing any documentation is technically a strategy of sorts, I won’t cover it here. Instead, I’ll talk about what, with tongue planted in cheek, I’m calling “oral tradition.” This looks similar to the “we don’t bother” strategy of documentation in that it doesn’t produce documentation artifacts. But there is a strategic difference.

What I’m driving at here is a decision to support API users via a form of hand-holding. You’re not publishing documentation that you ship alongside the API, but you do make the effort. Instead of giving them docs, you actually talk them through it or, potentially, work on it with them. You might supplement this with ad-hoc communication, such as emailing them an example.

If you work on a product like Trello, this sounds insane. But consider that not all APIs have equal constituencies. Perhaps you don’t generally support an API at all, but you’ve opened up some of your code to a major B2B client for integration. In this case, it’s so custom and specific that creating documentation makes no sense.

Using MS Word or Something Similar

Let’s move past the case of highly specific APIs for custom partners and into the realm of broader, more general consumption. When you throw your API open to the public or to any arbitrary paying customer, you need something tangible.

One tried-and-true way of doing this is to write user manuals in some form or another. This has roots going all the way back to man pages, and probably beyond that. Whatever the particulars, you put your API documentation into some digitally or physically distributable format. MS Word is a common choice, given its ubiquity and formatting capabilities.

But whatever you choose, the mechanics are the same. A developer or technical writer goes through the API and, well, writes about it. This generally includes everything I mentioned under “what is API documentation” and probably more. After all, it tends to have the feel of writing a book, naturally lending itself to verbosity.

This is a well-worn path to pleasing your users, and it has a lot of merits. The main downside, however, is that it’s extremely labor intensive.

Automated Documentation From the Outside In

Since historical methods for generating API documentation proved so labor intensive, it should come as no surprise that people used automation to relieve this pain. While you certainly can fire up MS Word and write all about your API, you no longer need to start from scratch like that. Tooling has caught up.

The first tooling approach that I’ll mention, I think of as outside-in API documentation. You build your API as you normally would, exposing the functions and means of interaction. Then you point a tool at your API’s surface. The tool parses it exhaustively and generates initial documentation based on its findings. From there, you mark it up as you see fit.

Swagger offers an example of this. You build a REST endpoint that you expose. Swagger takes that contract as input and generates your initial API documentation from there.

Automated Documentation From the Inside Out

Now let’s consider a complementary approach. If you think of outside-in API documentation as black box, we’re now talking about its white box counterpart.

Here’s how this works in concept. Given the source code for an application with an API, you use that source code to produce the API documentation. This happens by inferring various properties of the API — member visibility, parameter and return types, exceptions generated, application behavior, and even code comments.

In fact, code comments can be an excellent means for this style of API documentation. GhostDoc works this way. Assuming that developers tend to create well-formed method header comments anyway, it uses those as the basis for generating help documentation. You thus kill two birds with one stone: commenting the code for maintenance purposes while generating documentation for API consumers. Developers never need to open MS Word (or whatever).

What Strategies Do You Have?

My intent here was to broadly cover some options and to offer heuristic advice. Having done the former, let me do the latter. Whatever you choose, you should automate it as much as you possibly can. This helps you cut down on your labor and save time and money. You should also pick something idiomatic to the techs you’re working with. If you’re in the business of REST endpoints, Swagger is great. If you’re building .NET tools, GhostDoc will be a huge help. You need to figure out what best suits your purposes.

But all that being said, there’s no way I’ve covered every possible approach to API documentation in this post. So, what are some of the things that you do? How do you handle accommodating consumers of your API? Weigh in in the comments!

CodeIt.Right Rules Explained, Part 10

October 10, 2017Erik DietrichArticles, CodeIt.Right, CodeQuality, ErikDietrich, Rules, RulesExplainedNo Comments

Like any good habit, I’ve settled into a cadence with the CodeIt.Right Rules Explained posts. They’re coming about once per month or so, and each one offers a deep dive into three of CodeIt.Right’s rules. As always, I’ll start by citing my two personal rules about static analysis, along with a brief explanation.

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

This isn’t a rhetorical game. I could condense the statements and say “learn the reasoning behind all suggested fixes.” But I say it the way that I do to call your attention to a decision that you face when it comes to static analysis warnings. Every time you encounter a warning, you must either choose to ignore the feedback or to address it. And regardless of which you chose, you should really understand the logic behind the suggestion. Otherwise, how can you possibly make the right call?

In that spirit, I’m going to offer up explanations for yet another three CodeIt.Right rules today.

(more…)

A Field Guide to Code Comments

October 3, 2017Erik DietrichArticles, ErikDietrich, GhostDoc8

For someone relatively new to the field of programming, the subject of code comments would cause some definite confusion. That’s because experienced folks in the field can’t seem to agree on the topic. Some call the practice a code smell and claim it’s to be avoided. Yet others tell you to do it. And still others strike the middle ground. Confused yet? I would be. At the very least, I’d conclude that it’s a matter of personal taste.

So today, I’d like to offer you something different. Instead of offering yet another opinion to the mix (though I do have one), I’ll check that at the gate and offer a field guide to code comments. How did they get here, why do some like them but not others, and what are the different kinds of comments you see? That way, you can form your own informed opinion, rather than hoping for consensus where none will likely emerge.

What Are Code Comments?

First, let’s level-set a little. For anyone that’s been programming for a while, this is a bit basic. But let’s look at what code comments are and what their origin story is.

When you write code, you’re writing instructions. A compiler or interpreter will take those instructions and turn them into actual commands that an operating system executes. In order for this to work, the compiler or interpreter requires very specific syntax and semantics. Code comments exist as a way for you to add free-form text into your code but without the compiler or interpreter paying any attention. This is generally accomplished by using a specific character or characters to indicate code comments, such as “//this is a comment.” Pay no attention to that text after the double slash!

Why do this? Well, in the most general sense, it allows you to add meta information to your code and thus to communicate with other programmers (or a future version of yourself). You can write a line of code and then, after adding the comment character, you can talk about that code.

Where did this come from? Well, I described its history in detail in this post, but it began as a way to add “remarks” to code that you wrote. In the early days of programming, many programming languages were extremely terse and littered with GOTO logic, so these remarks were absolutely critical for code readability.

(more…)

Released: GhostDoc v5.8

September 28, 2017Serge BaranovskyGhostDoc, News, Releases, UpdatesNo Comments

GhostDoc v5.8 is a critical update for VS2017 users. Includes VS2017 performance and stability improvements, minor enhancements, and bug fixes.

GhostDoc is no longer crashing VS2017 when working with .NET Core projects
Issue when Document File action duplicates existing <seealso> tags for a class
Issue of all solution project unchecked when opening the Build Help Documentation dialog first time

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/

Code documentation and code comments are different, like red and green apples.

Code Documentation and Code Comments Aren’t the Same Thing

September 26, 2017Erik DietrichArticles, DocumentationNo Comments

Often, you hear “code comments” and “code documentation” used at least somewhat interchangeably. Perhaps the idea of code documentation has a little more formalism to it, in passing. And code comments may cover a bit less ground.

But still, I hear the terms serve as synonyms for one another. And I hear this in particular when it comes to the actual construct of code comments — meaning, literally, the feature of compilers and interpreters that allows you to say, “Disregard everything after these two slashes. I’m editorializing for the benefit of other humans.” “Comment your code” and “document your code” offer the same mandate.

But I find that problematic. And it’s not just because I’m some kind of stickler for semantics. I think this causes us to have weird arguments, sometimes nonsensical and sometimes unnecessary.

Code Documentation vs Code Comments

To explain myself and my reasoning, I’ll offer definitions for both terms.

Code comments: any meta text you put in source code.
Code documentation: creating a conceptual maintenance manual for your source code (in the dictionary sense of documentation).

Having established that, let me stave off some possible objections. First, you might ask, “Isn’t the entire point of code comments to help create that user manual?” In theory, maybe. But in practice, come on, you know better. People use comments to add legal boilerplate, express themselves with ASCII art, try their hand at comedy, and probably even to gossip.

Secondly, maybe you’re someone that concedes that people do use comments this way, but you say that it’s abuse. In other words, sure, that happens — but it shouldn’t. If people did code comments right, they would all constitute code documentation. But I would still argue against this idea. Code comments can represent note-taking. “Note to self” and “note for later” both count.

So let’s create a relationship definition. Code documentation means creating a maintenance manual for your code, and that manual may or may not use the code comment as a medium.

I’ll also say that I think you should document your code, but it doesn’t matter terribly if you comment it.

(more…)

Using CodeIt.Right at Scale on Large Codebases

September 19, 2017Erik DietrichArticles, CodeIt.Right, ErikDietrich, RulesNo Comments

If you’ve worked with Visual Studio for any length of time, you’ve probably noticed an inverse relationship between convenience and performance. Visual Studio is powerful on its own. And it gets a whole lot more powerful once you start adding plugins. But sometime between that clean Visual Studio install and your 20th helpful plugin, a noticeable slowdown occurs. The user experience starts to suffer.

Of course, this isn’t unique to Visual Studio. It applies to pretty much anything with a plugin ecosystem, such as a WordPress website or your browser. In all of these cases, you have to weigh the value of the plugin against the performance hit you suffer. But in the world of Visual Studio plugins, you often have more and better options than just disabling the plugins. You can manage them.

This is true of CodeIt.Right, SubMain’s automated code review tool. With a tool that provides code analysis, you might think your only lever to pull comes from turning warnings on and off. Not so. CodeIt.Right supports the concept of profiles, which let you set up different sets of rules to execute at different times. And this can really help the efficiency of your development efforts.

The Rationale for Profiles

Over the years, I’ve helped a lot of shops adopt the practice of automated unit tests. One of the most critical pieces of advice I give often surprises people initially. I tell them that a fast test suite is absolutely critical. And I’m far from alone in giving this advice.

Now, this may seem obvious in a sense. All things being equal, faster is, of course, better. But I go so far as to argue that your unit test suite becomes extremely ineffective if it takes a while. In fact, a long-running test suite becomes nearly useless. Why? Because it actively discourages people from using it. If your unit test suite takes minutes or even hours to run, how frequently will you really run it?

You hear about this a lot in the context of unit testing — not as much in other situations. But it’s just as important elsewhere. If your automated code review tool takes a long time to run, people will stop running it. This isn’t laziness on their part. Quite the contrary, in fact. They stop running it because it slows them down and prevents them from getting their work done.

So to get the most out of a tool like this, it’s extremely important that you pay close attention to how efficiently you’re using it. The world of automated unit tests has the notion of a “test pyramid,” in which you have quick tests that you run all of the time and longer running ones that you run less frequently. Let’s take a look at different strategies for achieving the same thing with CodeIt.Right. How can you segment your analysis to get the best of both worlds: speed and thoroughness?

(more…)

CodeIt.Right Rules Explained, Part 9

September 12, 2017Erik DietrichArticles, CodeAnalysis, CodeIt.Right, CodeQuality, ErikDietrich, Rules, RulesExplainedNo Comments

In what has become roughly a monthly affair, I’ll do another CodeIt.Right Rules Explained post today. This marks the ninth such post and roughly nine months of the series. In a now-familiar refrain, I’ll start off by citing my two personal rules about static analysis followed by a brief explanation.

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 might seem I’m playing rhetorical games here. After all, I could condense this to say “learn the reasoning behind all suggested fixes.” But I say it the way that I do to call your attention to a decision that you face when it comes to static analysis warnings. Every time you encounter a warning, you must either choose to ignore the feedback or to address it. And regardless of which you chose, you should really understand the logic behind the suggestion. Otherwise, how can you possibly make the right call?

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

Avoid Unsealed Attributes

Let’s start off with something conceptually easy to understand, at least in terms of the problem. You’ve no doubt encountered the attribute construct before, whether you realize it or not. Here’s a quick code example.

[TestMethod]
public void Adding_10_And_15_Returns_25()
{
    var calculator = new Calculator();

    int result = calculator.Add(10, 15);

    Assert.AreEqual<int>(25, result);
}

That thing at the very top? TestMethod? That’s called an attribute.

In .NET, attributes amount to declarative metadata about the code element they describe. For instance, we use the attribute in the code sample to declare that this is a test method. You write this code to opt into the MS Test framework. The framework then looks for that attribute and treats any method decorated with it as a unit test method.

How do you get access to this magic? Let’s look at a trivial, ridiculous, and hopefully memorable example. First, I declare the attribute.

public class ApprovedByErikAttribute : Attribute
{

}

With that on the books, I can now meander through the codebase, making my opinion felt. Let’s say I encounter a class called Circle. It’s a bit simplistic, but it’s off to a good start. I approve this class! Let’s let everyone know.

[ApprovedByErik]
public class Circle
{
    private readonly int _radius;

    public Circle(int radius)
    {
        _radius = radius;
    }
}

Alright, everything looks great here. Except I run a CodeIt.Right analysis on this and I see a warning: “avoid unsealed attributes.” Well, inheritance is certainly less fashionable these days, but CodeIt.Right flags this as a performance issue. What gives?

Well, you access this attribute metadata via reflection, which, as it turns out, is expensive in and of itself. You have to pay the piper for this magic. But doing this with unsealed attributes is even more expensive since the .NET framework methods for accessing attribute information search the entire inheritance hierarchy by default. Sealing your class basically tells them not to bother looking any further. It’s also a really easy fix: just add the keyword “sealed” to your attribute class and call it a day.

Avoid Excessive Complexity

Let’s change gears here and switch over to a CodeIt.Right rule under the heading “maintainability.” This one counsels you to “avoid excessive complexity,” and I won’t include a code sample here. Why? Because in order to do that, I’d have to come up with a ridiculous method that would take up half of the space of this post. I’ll come back to that, though.

When CodeIt.Right refers here to “complexity,” it’s not offering some vague, subjective take. Rather, it refers to something measurable and specific. I’m talking about the idea of cyclomatic complexity. Cyclomatic complexity measures the number of independent paths through a method. So if you have a method that just returns the sum of two integers, then you have cyclomatic complexity of one. But if you add a guarding if condition, you now have a cyclomatic complexity of two.

To conceptualize the idea, think in terms of control flow logic. If and else conditionals add to a method’s cyclomatic complexity. So do while loops, for loops, ternary operators, and switch statements. The more decision logic occurring in a method, triggering different ways to step through it, the higher the cyclomatic complexity.

Out of the box, CodeIt.Right will flag methods with cyclomatic complexity of more than 25. That means it will flag any methods with more than 25 independent paths through them. Make no mistake — that is an insanely complex method that will cause you maintenance headaches. And now you can understand why I wouldn’t want to dream up and post such a thing. It’d just be a tortured rat’s nest of nested loops, conditionals, and perhaps even some goto logic for good measure.

Enforce Warning Level 4

Last up today, let’s look at something a bit off the beaten path. This falls under the heading of “general” in CodeIt.Right’s rule categorizations. And it speaks to properties of your project, rather than of your code.

If you right click a project in Visual Studio and select “project properties” (or use keyboard shortcut alt + enter), you get a screen that lets you modify aspects of the project itself. Select the “build” tab, and you can modify settings about how MS Build compiles the project. Of interest today, we have the “Warning Level” setting under “Errors and warnings,” as shown here.

By default, your projects come with warning level 4 pre-selected. And 4 is also the highest level of warnings. You can check out the details of each warning level here.

The warning messages to which it refers show up in your “errors” window when you build your project. That window will show you any compiler errors, but also compiler warnings, such as unreachable code or unused variables.

When you select something less than 4, you’re telling your build to show you fewer warning messages. If you go all the way down to 0, you’re telling it show you no warnings at all: “If you’re technically able to build this, then build it and tell me nothing.” CodeIt.Right warns you about this practice because it’s generally a bad idea to ignore compiler warnings. The vast majority of the time, they’re warning you about something legitimately wrong with your code.

If, on occasion, the compiler warning system yields some false negatives, you have other recourse to ignore them. You don’t need to engage in blanket disabling. CodeIt.Right warns you about this course of action because it’s almost certainly overkill for what you want to accomplish.

Until Next Time

I’ve tried to offer yet another eclectic mix of code issues in this post. I started with a lesser known bit about defining your own attributes that actually relates to performance. Then I took you through the general issue of high cyclomatic complexity and wound up with a general suggestion not to ignore wholesale warnings in your codebase.

And that last bit of advice, in fact, parallels my general advice on static analysis. The compiler is yet another form of static analyzer, and you should probably heed its advice or else have a very, very good reason not to.

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

Released: GhostDoc v5.7

September 7, 2017Serge BaranovskyGhostDoc, News, Releases, UpdatesNo Comments

A new GhostDoc update is available now – version 5.7. Includes VS2017 performance improvements, minor enhancements, and bug fixes.:

Improved performance loading solutions in VS2017 by moving it to an async thread
Resolved issue related to license activation with the VSIX install in VS2017
Fixed “Active content” security warning in the Comment Preview window
Added progress indication for the Document File/Type batch actions with large number of the members to be documented
Enabled .cshtml and .vbhtml file extensions for spell checking
Improved performance of the Document File/Type batch actions
Fixed issue related to the PathTooLongException when building help 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/

Captain Obvious will tell you that there are certain comments to avoid, such as documenting the obvious.

Not All Code Comments Help: What Should You Avoid?

September 6, 2017Erik DietrichArticles, ErikDietrich, GhostDocNo Comments

The debate over whether or not to comment your code rages on, showing no signs of stopping. Catalogers of anti-patterns include code comments as a code smell because they explain problems in your code instead of fixing them. Not so, counter people on the other side of the aisle, sometimes angrily. No doubt the conversation becomes only more civil and even-keeled from there.

So-called religious wars like this emerge for a variety of reasons. Human nature causes us to get attached to our own decisions and to assume people making different choices than us do so as a result of personality defects. But in the case of code comments, even more complicating factors exist. One person, when speaking about code comments, may mean inline explanatory comments. Another may mean documentation for the sake of IntelliSense. People will argue angrily before realizing they’re not even talking about the same thing. Then folks come along and try to find a diplomatic, consensus-building middle ground.

Today, I’m going to do none of those things. I’m going to utterly punt on words of wisdom about how, when, and why you should comment. Instead, I’ll have a bit of fun by walking through something a lot of us can probably agree on. I’m going to talk about the sorts of comments that nobody should write, whatever your stance on the broader issue of commenting.

If you’re a general comment-hater, then of course you’ll agree that people shouldn’t write these comments because they shouldn’t write any. But even if you’re a comment enthusiast, you’ll concede that not everything that people ever put after two slashes (or a pound or whatever) deserves to be immortalized in your codebase.

Here are categories of comments that should not be.

(more…)

Some styles of code analyzer make use of the abstract syntax tree.

The Different Styles of the Code Analyzer

August 29, 2017Erik DietrichArticles, CodeAnalysis, CodeIt.Right, ErikDietrichNo Comments

Perhaps you’ve heard of the concept of a source code analyzer before. I expect that many reading have, at least in passing. But I’d also be willing to bet that the term strikes you as somewhat vague and that everyone reading will picture slightly different things when they hear the term. So today I’ll do what I can to clear that vagueness up.

Static Code Analyzer: the Backstory

Let’s start with origin and motivation. As software developers, we automate things for a living. This gives us the unique ability not only to make others more efficient at doing their jobs but also to turn this same idea on our own work. We constantly seek to automate our own processes.

The code analyzer represents this exact idea. Boiled down to its essence, you can think of it quite simply. I’ll give a hypothetical example. Say you spend a lot of time looking through your code, making sure that all methods and properties have Pascal casing. As you waste another hour doing this, it occurs to you that you could probably write a program to do it automatically, taking your source files as input. And it then occurs to you that such a program would actually be better and more efficient than you at this task. Well, you’ve just conceived of the static code analyzer, if a very rudimentary one.

Code analyzers emerged as a result of this exact sentiment. In the late 1970s, engineers at Bell Labs created a utility called Lint. Its mission? To parse C code, looking for “likely bugs.” This concept had such a profound effect on the industry and such staying power that you’ve undoubtedly heard about a “linter” for your language of choice. These all descended, conceptually, from this original built nearly four decades ago.

The Proliferation of Code Analyzers

During the time between the release of the original Lint and now, the code analyzer has evolved considerably. Lint and similar programs were known as “first generation” static analyzers. These are characterized by usefulness, but also by suffering from problems of low signal-to-noise ratio.

Years later, as processing power improved considerably, the second generation of static code analyzer emerged. In the second generation, tools stopped treating the source code as simply text. Instead, these tokenized the code and stored it in semantically contextual representations. In other words, these tools grokked the source code. And they used this understanding to do much more sophisticated vulnerability analyses. But while this cut down considerably on the signal-to-noise ratio problems, it didn’t scale terribly well.

As processing power continued to grow by leaps and bounds, a third generation emerged. This generation used abstract syntax trees, better hardware, and more nuanced heuristic approaches to do deeper analysis than generation 1, and with better scale than generation 2. And it’s these third generation tools with which you are familiar.

These generations, however, represent a fairly shallow categorization in and of themselves. They address the advancing state of the art, but not the breadth of tools that we have at our disposal. Today’s static code analyzer has different flavors, and I’ll speak to some of those here. With an industry full of people looking to automate as much as possible, it should come as no surprise that a diverse ecosystem of code analysis options has emerged.

(more…)