So far we’ve had the opportunity to take a deep C# dive on arrays, lists, and the very valuable enum. Today we are going to stay in the System.Collections.Generic namespace and learn about a structure that’s designed for lookups—the C# dictionary.
It’s a sad fact that code documentation rarely gets the attention it deserves. That’s a shame since it’s often a crucial part of the final product. Bad documentation often makes the difference between how easy it is to fix a bug a year later or whether a customer chooses to integrate with or buy your software.
Many software teams say they don’t have the time or resources to do documentation. I recommend integrating it with the process, but I’ve seen this go wrong way too many times. Erik Dietrich describes projects that required XML doc comments for every single method and class. I was on a project where every story in Jira required corresponding documentation. The developers reluctantly wrote a lot of documentation that we believed no one would ever use. And we were right.
With documentation, it’s key you have a well-developed documentation process. And you should also take advantage of modern tools to save time and identify documentation gaps.
Documentation IS a product, even if it’s only used internally. Once you see it as a product, treat it like you do your other products. At the bare minimum, you want to have a collection of use cases to measure the success of the final product. Who is your audience? How will the documentation be used? What information do users need to successfully do these things?
Once you have a vision, you should consider tools that save time and prevent duplication of work. No one wants to have to write code and then go into some other system to write documentation. It doesn’t help that the other system is usually a mediocre wiki or content management system.
In 2018, there’s no reason to do this. Modern documentation automation products like GhostDoc save time and help with consistency. GhostDoc can generate code comments automatically from within Visual Studio. With GhostDoc Pro, you can use these to generate help files.
I know, you’re skeptical of automated comments. You’ve probably seen some pretty baffling documentation that was so obviously autogenerated. That’s why I recommend it as a tool, not as a substitute for a good process.
It’s critical that you have an editorial process as well. Would you push unreviewed code to production? Then why push unreviewed documentation? On my teams, I have documentation go through peer review just like any code does.
GhostDoc has some awesome features for editorial review. You can easily mark and track comments that are auto-generated. That allows reviewers of any kind to find and evaluate them. In my experience, many are good enough, but there are still many that need some additional explanation.
No one likes outdated documentation that doesn’t work. GhostDoc can find documentation comments that are out of sync with the parameters, return types, and type parameters of the associated code.
But peer review isn’t enough to evaluate the software overall, and it’s not enough for documentation. Documentation should also be reviewed as a whole. I recommend doing this as a team by having other key stakeholders involved as well.
I also recommend having other non-engineers review documentation. How many developers complain that marketing doesn’t “understand their product”? Well here’s an opportunity to finally write something that helps. The best documentation is usable on some level to marketing, product, project, and sales teams.
Many companies do user research for their software. If your documentation is user-facing, consider doing some user research on it. At Write the Docs Portland this year, Jen Lambourne gave a great talk about how their company does user interviews for documentation. She said, “It’s a way to find what works rather than just what’s popular for us.” In the end, you’ll also gain key insights about your product beyond just documentation. Many teams use this research to develop new features, drive marketing, and identify product weaknesses.
Many teams also use traditional user analytics tools like Google Analytics or Pendo. This allows them to capture data on how users find and use documentation.
If the documentation is internal, you still want to have some basic user research. For this, I often do what I call “cross-training.” When I was a (not very) competitive swimmer, we sometimes did cross-training. It was where swimmers would do non-swimming dry-land exercises like running and weightlifting. This increased our flexibility and strength in ways that swimming alone couldn’t.
Use your documentation as a cross-training tool. Have one team review another’s documentation. This reduces the bias toward writing documentation that is too difficult for non-experts. It also builds organizational capacity—now you have more developers in your organization who know your software well.
Documentation users and writers are EVERYWHERE in software organizations. Many companies now have practices and working groups for developer tools, culture, and architecture. Why not have one for documentation?
This kind of support signals that you believe documentation is important. It also helps bring together experts to develop best practices and share knowledge. I’ve been in more than one of these groups where people didn’t even know each other before. They didn’t know anyone else in the company did documentation!
Bad, incomplete, and absent documentation, whether user-facing or internal, is a risk. Great documentation is an asset. If you’re not thinking about documentation, you’re behind.
Take the sting out of documentation by developing a modern documentation process. That means automating what you can, then reviewing it as a whole to see whether or not it makes sense and is useful. And when the documentation is “done,” analyze usage and keep improving it.
Learn how GhostDoc can help to simplify your XML Comments, produce and maintain quality help documentation.
When I last looked for software engineering jobs, I came across a post that looked perfectly normal until I got to a line that said, “Participate in daily code inspections.” What the heck was a code inspection? It sounded pretty serious. And we’d be doing it every single day?
A quick Google search brought me to a Wikipedia page for “software inspection,” which told me that “code inspection” was pioneered in the 70s at IBM. My grandfather’s cousin happened to work there at the time, so I asked him to weigh in. He said they were a “formalized effort by team members to go over each other’s code.”
But things have changed a lot since the 70s. And often, vintage terminology is a sign of other outdated development practices. (more…)
It’s time for a deep dive into yet another three CodeIt.Right rules. In case you’ve missed it, this continues a post series in which we, well, do a deep dive into the CodeIt.Right Rules.
CodeIt.Right is an automated code review tool, making it fall under the broad heading of static analyzers. It checks your source code against a set of rules, both ones that you customize and a set that comes out of the box. In this series, we’re focusing on the latter, since those are the ones that will obviously apply to everyone.
Followers of this series will know that I always kick the posts off by listing two static analysis rules of thumb that I advertise as good ideas.
If this seems a little obtuse, it’s probably because you could condense these two rules into a single one by logical implication: “always understand a suggested fix.”
But I deliberately choose not to phrase it this way, opting for the two separate rules. I do this to emphasize your choice: ignore the warning or implement a fix. If you decide to ignore the warning, you should do so only when you’re fully aware of the risks of doing so. If, on the other hand, you decide to fix the warning, you should always understand what you’re doing when you change your own code. Otherwise, you’re programming by coincidence.
Don’t program by coincidence. Instead, take a look at today’s three rules.
We’ve discussed arrays and lists in C#. This time, we’ll take the same journey with a funky little type called the enum. C# enums are very useful constructs, but they have some quirky behavior that can bite you if you’re not careful.
Let’s now see what makes enums tick, how to use them effectively, and what to be careful of when using them. (more…)
Does your team use a coding standard? If the answer is no, then I’m afraid you’re missing out on a lot of important benefits. This post will help you create (and automate) C# coding standards using Submain’s CodeIt.Right. I’ll start out by making the case that you need a coding standard. We here at the SubMain blog have already covered that subject, of course, but I’ll revisit it anyway.
With that out of the way, I’ll go on to explain the most common problems that occur when teams try to implement coding standards and code reviews manually.
Finally, I’ll show you how automation can heal these pains, and how to use CodeIt.Right for doing so. Let’s get started. (more…)
Since the beginning, web developers have always needed to transport and store data, and there’s an entire generation of web developers that has only ever used JSON (JavaScript Object Notation) for that purpose. That choice makes sense; JSON is easy to read and conforms to JavaScript syntax. Some developers may not have even heard of XML (eXtensible Markup Language). XML was also designed to be both human- and machine-readable. Its purpose is primarily to handle the transportation and storage of data. And this data exchange was not meant for web only. Most importantly, distributing data of different flavors works fantastically well with XML, all because XML is designed to be highly flexible within a strict structure. Yet JSON continues to be the first choice for many developers. Which prompts the question: is XML dying?
In this article, we will explore the differences between XML and JSON. We will address which conditions best suit which format. At the end, we’ll dig into a few scenarios where XML will continue to play a crucial role in data exchange.
But the build configuration system in .NET goes beyond just transforming the config file. There is a whole system of solution and project configuration management that you can use to your advantage.
A project configuration contains a set of properties to be used when building the project. Likewise, a solution configuration contains a set of properties at the solution level. But it also contains the selected project configurations for that solution configuration. An example should clarify.
Not that long ago, we published a post about the fundamentals of the C# array. Today’s post will continue the trend, covering the C# list. Don’t worry: if you’re a beginner, you’ll also benefit from this post. Instead of brushing up, you’ll get your first contact with this incredibly useful data structure.
As in the array post, we’ll discuss what a list is. We’ll learn how to use it, what its most common operations are, and how to avoid some common pitfalls. With that in mind, you’re ready to see what the C# list has to offer you.
Today, we bring you another post in the CodeIt.Right Rules Explained series. Up until this point, I’ve been chronicling these posts by their number in the series, but I realize that the numbering: is both academic and relatively easily inferred via the posting category. Nevertheless, in spite of changing the approach to the title, I’ll recap the premise, as I always do.
CodeIt.Right is an automated .NET code review tool. That means that it automatically analyzes your code and applies rules to it. In the posts in this series, I explain those rules in detail.
In all posts in this series, I start out by listing these rules of thumb for static analysis in the hopes that repetition makes the point.
I’ll also explain, as I always do, that I don’t use this phrasing to seem clever or because I can’t figure out the more succinct logical conclusion that these two statements imply: that you should always understand why the tool is suggesting a fix.
I do this because static analyzer warnings present you with a choice: address the warning or ignore it. And, whichever path you choose, you should do so deliberately and for the right reasons. Decide to ignore the warning because you think what you’re doing isn’t actually a problem. Or decide to address the warning because you understand that what you’re doing is problematic and not because you’re programming by coincidence. Always know what you’re doing.
And with that, let’s dive into today’s rules.
