It’s time for yet another discussion on an important C# construct.
We started this journey with the C# array. Then we covered the list and enum. And, finally, the dictionary.
Today, we cover yet another fundamental but often misunderstood type in C#: the string.
Here on the SubMain blog, I’ve already covered how to use CodeIt.Right to Create C# Coding Standards. Today Visual Basic gets the same treatment. In case you haven’t read the previous post (or any post in this blog at all), I’ll briefly explain what these posts are about.
CodeIt.Right is an automated code review tool. It checks the source code of your application against a set of rules (which can be the standard rules or custom ones), giving you instant feedback on its quality.
Similarly to the previous post, I’ll explain how you can create a Visual Basic coding standard by using CodeIt.Right. If your team doesn’t already know and use coding standards, then that’s a great opportunity for all of you to learn about all of the benefits you’re missing out on. I’ll begin by arguing that you need a coding standard. The SubMain blog has already covered that subject, but I’ll quickly revisit it.
Then I’ll go on to explain the usual problems teams face when trying to implement coding standards and code reviews in a totally manual way.
Lastly, I’ll explain how automation can solve those problems and how can you do so with the help of CodeIt.Right.
Time for another post in the CodeIt.Right Rules Explained series. In case you haven’t read any of the posts in the series, here is a short explanation.
CodeIt.Right is an automated code review tool, which analyzes the code of your application code against a set of rules, giving you instant feedback on its quality. Each post in this series explains three of those rules.
If, on the other hand, you’re a follower of this series, nothing above is any news to you. You’ll also know that we always start the post with the following sentences:
Nope, we’re not trying to sound clever, funny, or anything. I know it’s obvious to you that we could just say, “always understand what the tool is telling you.”
We don’t say it that way, though, and there is a reason for that. We want to make it very clear you have two options: to either implement the suggested fix or ignore the warning whatsoever. If you implement the fix, you should do so when you are fully aware of why that makes your code better. If you ignore it, you should also be aware of the dangers of doing so.
With that said, let’s get started with our first rule for today.
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…)
