SubMain.com
YouTube
RSS

C# Comments: A Complete Guide, Including Examples

Carlos SchultsArticles, CarlosSchults, CodeBasics, Documentation, GhostDocNo Comments

C_sharp_comments_sign_with_arrowTime for another C#-related post. We’ve already covered a fair amount of the language’s keywords, types, and concepts in previous posts. Today’s post covers comments, a topic that you might think is trivial. My mission in this post is to convince you otherwise. True, comments are far from being the most exciting programming topic you could think of, I admit. And sure, comments have gotten a negative reputation over the years. But there’s more to comments than you might think.

In this post, you’ll learn about the definition of C# comments, followed by common justifications for their usage. Then we’ll proceed to show you the different possible types of C# comments and how to use them in practice. Let’s get started.

(more…)

DateTime.Now: Usage, Examples, Best Practices, and Pitfalls

Carlos SchultsArticles, CarlosSchults, CodeBasics, CodeIt.Right, CodeQuality2 Comments

Datetime.now_code_snippet_hand_drawnIf I were to summarize DateTime.Now using one word, it would be “don’t.” DateTime.Now is a very problematic way of retrieving the current date and time, and you should—almost—never use it.

But that would make for a super short post and an incredibly unhelpful one at that. It’s not enough to say you shouldn’t use a given approach without going further to explain why it’s problematic and what to do instead.

So, that’s what we’re going to do now—take a look at the dos and don’ts of DateTime.Now as well as a few best practices and alternatives. Let’s get started.

(more…)

Software Documentation: What You Need to Document and How

Vlad GeorgescuArticles, Documentation, GhostDoc, VladGeorgescuNo Comments

 

A hand writing software documentation on paper

Software documentation is all about bringing clarity into a code baseline. It provides clues to clarify the meaning of certain code structures. For this purpose, we use best programming practices and tools to clarify our software. When documenting software, we aim to minimize time spent hunting for meaning. We want anyone using or reading our code to know exactly what we meant when we wrote it. In addition, they should also know how to use our code without having to look for extra clues. Whether it’s an API, a suite of REST services, or simply a method in your code, it should all be clear.  When things are not clear, you have to dig up the meaning from other parts of the code, and this is a waste of time.

In this article, we’ll explore what information to document and how to do it. Lastly, we will talk about presenting our software documentation.

(more…)

CodeIt.Right Rules Explained, Part 22

Carlos SchultsArticles, CarlosSchults, CodeIt.Right, Rules, RulesExplainedNo Comments

CodeItRight_Rules_22Welcome back to the CodeIt.Right Rules Explained series. For those of you who haven’t seen an installment in this series, let’s explain what it’s all about. CodeIt.Right is a tool that performs automated code review for .NET. It checks your code against a set of rules, giving you valuable feedback on its quality. Throughout the series, we’ve been explaining these rules, always three at a time.

In every post in this series, we start with the following two rules of thumb:

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

Trust me—we don’t phrase it this way to sound funny or anything. It’d be the same thing to say “figure out why the tool is suggesting this.” But we don’t. And here’s why.

Each time CodeIt.Right shows you a warning, you must decide to either address it or ignore it. Make that choice for the right reasons. Ignore the warning when you’re truly convinced it doesn’t apply to your situation or doesn’t provide enough benefits. Don’t ignore it because you don’t understand it very well and don’t feel like handling it.

Now that you understand what this post is all about, let’s get to today’s three rules.

(more…)

Released: GhostDoc v2018.2

Serge BaranovskyGhostDoc, News, ReleasesNo Comments

A minor feature update build v2018.2.19030 is now available

Changes in v2018.2

  • GhostDoc now uses Async integration with Visual Studio with background load enabled. This minimizes the GhostDoc load on Visual Studio startup.
  • Added new setting Options -> Solution Options -> General -> “Use <inheritdoc /> tag for inherited comments”. When checked, GhostDoc will insert the <inheritdoc /> tag instead of copying the base member documentation. Note: When using the <inheritdoc />, remember it is a custom tag and you must use GhostDoc to generate help documentation and VS Intellisense files.
  • Modified Properties, Methods, Indexer, Event and Constructor T4 templates to insert the <inheritdoc /> tag instead of copying the base member documentation – when UseInheritdocTag setting is True.
  • Encryptions within GhostDoc are now FIPS compliant.
  • Abbreviations dictionary now allows abbreviations with an empty value. This enables skipping abbreviations and word parts like prefix, suffix etc.
  • Now a new XML Comment template is generated when Visual Editor opens using Ctrl-Shift-D for the member that does not have XML Comment.
  • Numerous fixes and improvements

For the complete list of changes, see What’s New in GhostDoc v2018

Download GhostDoc

Feedback

We appreciate your feedback on the new features; please email us at support@submain.com or post in the GhostDoc Forum.

 

5 Ways You Might Be Failing at Software Doneness

Vlad GeorgescuArticles, CodeBasics, VladGeorgescuNo Comments

Meat_thermometer_not_reading_even_close_to_rareOne of the most anticipated acts at a circus is the juggler—a performer who can move five or six or more balls in the air at the same time. The really complicated juggling acts, however, add something extra to wow the crowd. The juggler first climbs some stairs, high up but still close enough for everyone to see. He’s on a platform. The overhead lights are dim while one bright spotlight is on the juggler as he starts to juggle—one, two, three, four, five, and six balls moving effortlessly through the air, all in balance. He’s good!

But now, a new spotlight illuminates everything to his right … and everyone is amazed. It’s a tightrope that runs across the entire stage to another platform. The juggler then turns and faces the tightrope while juggling the six balls, and he starts walking slowly across. Step by step, balancing and juggling, he gets to the other side. He then turns to face the crowd, catches each ball, and bows. The crowd roars in delight! He’s done!

In many ways, a software developer is a juggler who is keeping many balls in the air while simultaneously walking on a tightrope. If you drop any balls or you walk in the wrong direction, you will fail. If, on the other hand, you get to the right destination with all the balls in the air, you get to stop, take a bow, maybe get some applause, and be done with your software.

(more…)

C# Interface: Definition, Examples, Best Practices, and Pitfalls

Phil VuolletArticles, CodeBasics, PhilVuollet2 Comments

C_sharp_interface_code.The C# interface isn’t exactly intuitive. Interfaces, in general, are common. We use them all the time. You’re using at least one interface right now as you read this article. Keyboards, mice, and screens are interfaces to your operating system. It’s the same concept with C# interfaces.

In this article, I’ll start with these familiar device interfaces as a metaphor for explaining the C# interface. I’ll use examples and alert you to some of the pitfalls. You’ll also learn about industry best-practices when using C# interfaces. By the end, you should have a clear picture of the C# interface.

(more…)

How to Document Code: 5 Ways to Help Maintenance Programmers

Vlad GeorgescuArticles, Documentation, VladGeorgescu5 Comments

Maintenance_guy_with_how_to_manualImagine you’re a software developer working on a financial application. One day you’re assigned (or, if you’re agile, you pick yourself) to implement changes to the overtime computation logic so your company can sell the application in France. In France, the official work week has 35 hours (lucky them) instead of the 40 hours in the US. Being new to the team, you’re not sure where to begin, so you start searching the codebase for the keyword “overtime.”

Let’s see the search results. No, no, no, maybe, no, no, maybe. Hmmm. OK, looks like it’s in this file, and then in this other file as well. Let’s take a look inside.

I see final static int HOURS = 8. What’s that? Looks like eight hours per day…maybe? Then final static int WEEK_HOURS = 40. Looks like 40 hours per week…maybe? Or maybe it’s in this method called getOvertime? I’m not sure where to find the logic I’m looking for.

This is a typical scenario when the meaning of the code is unclear. And it’s a time suck.

What would help you as a developer when modifying and fixing existing code? It’s easy to complain about code written by someone else, but what about the code you write yourself? What do you include so you can help the maintenance programmers who’ll come after you?

The simple answer is that you have to document your code so your logic is clear, easy to understand, and easy to change.

This article will explain how to do that. We’ll explore what software maintenance is. Then we’ll talk about how to document our code so we can help the other developers who’ll be fixing and modifying the code we write. And since we often get to fix and modify our own code, this will be an article about how we can help ourselves, too.

(more…)

Code Contracts: A Technique to Cut Down on Bugs

Carlos SchultsArticles, CarlosSchults, CodeQuality1 Comment

Two Hands Handshake signifying code contractsRent, employment, house buying: you name it. If you’re an adult, chances are that you’ve signed several contracts in your life (and will probably sign many more). A contract is an agreement that defines the rights and obligations of two or more parties in order to accomplish something.

Having a proper contract in place is a powerful tool to clear doubts about what you’re allowed or not allowed to do to the apartment you live at, for instance. A contract also defines penalties for the parties that fail to fulfill their part of the agreement. If you don’t put down your house payments when they’re due, you’re pretty much guaranteed to suffer some consequences.

Contracts are everywhere in the real world. But what would it look like if we could use something similar to contracts in our code? For instance, what if we could specify “clauses” that defined the conditions required at the start and end of a function? Or maybe that specified and enforced the invariants of our objects? In this case, I’d say our programs would definitely improve in readability, safeness, and self-documentation.

And now, what if I told you something like this already exists?

(more…)

exasperated programmer with her head on a desk resenting code review practices

The 4 Code Review Practices That Make Devs Quit

Carlos SchultsArticles, CarlosSchults, CodeReviewsNo Comments

If we start with the premise that having code reviews is better than not having them, the next step is to figure out how to make them better. And though we’re all aware that code reviews are a good thing, they can quickly degenerate into toxic scenarios. We don’t want that.

In this post, we’re going to see four code review practices that can make developers feel frustrated and alienated. In the more extreme cases, developers might even leave a company to escape from what they perceive as tyrannical, nonsensical demands. Keep reading to learn what those practices are, how to avoid them, and how to leverage the benefits of automation in your code reviews to prevent many of these toxic scenarios from happening in the first place

Once you know that, you’ll be empowered to turn your code reviews into healthy processes that lead to higher code quality and more happiness for the developers in your team. Let’s get started! (more…)

Menu