SubMain.com
Google+
YouTube
RSS
You need me in code comment

4 Reasons Why We Need Code Comments

Mark HenkeArticles, CodeBasics, CodeQuality, GhostDoc, MarkHenkeNo Comments

Why do we need code comments? I would not be surprised if your first answer is, “We don’t.”

I get it. Senior developer after senior developer has taught us that “comments are bad.” And we cheerfully nod our heads, saying, “I am smarter for not using them.” We grin smugly when we see one of our juniors make the “mistake” of using comments in their code.

But as much as we sometimes abuse them, we still need comments.

I know comments don’t affect the code’s behavior. I understand how they can get stale and stop making sense. I am all for writing clean code, and I do my best to ensure my variables, methods, and class names describe their intent as accurately as possible. If I see dead code lying around in the comments for a while, I delete it.

But here is the bottom line: we need code comments because there are some things they do better than plain code. Here’s why.

(more…)

CodeItRight_Rules_20

CodeIt.Right Rules Explained, Part 20

Carlos SchultsArticles, CarlosSchults, CodeIt.RightNo Comments

Time for yet another deep dive into three more CodeIt.Right Rules. For those of you who don’t know about our CodeIt.Right Rules series, here’s a brief explanation.

CodeIt.Right is one of the tools offered by SubMain. It’s a static code analyzer tool or, more specifically, an automated code review tool. CodeIt.Right works by checking your code against a set of rules and giving you instant feedback on how to solve potential problems. It even offers automatic fixes when applicable.

In each installment on this ongoing series, we explain three CodeIt.Right rules, usually picked from as diverse a category as possible, to showcase the flexibility and breadth of the ruleset.

Readers of this series know that we like to start these posts by stating two things:

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

Yeah, you could simplify this down to “always understand a suggested fix.” But I choose to not put it that way since I want you to really think and consider your options. If you decide to ignore a fix, do so understanding the consequences. On the other hand, if you accept a suggested fix, do it with a full understanding of how that’s going to benefit your application.

With all that in mind, let’s get to today’s rules.

(more…)

Web forms icon partying

The Case for Web Forms, Even in 2018

Mark HenkeArticles, MarkHenke2 Comments

It seems easy for people to say things like “LOL, Web Forms” or “Web Forms is dead.” Web Forms sometimes gets very little respect from the .NET development community. We look forward in time, forgetting the giants on whose shoulders we stand. It was the dominant way of making websites in .NET for many years. Is it really a remnant of a bygone era? Or does it have a vibrant existence in places oft overlooked?

(more…)

Web.config code example

Web.config: 5 Common Mistakes and How to Avoid Them

Mark HenkeArticles, CodeIt.Right, CodeReviews, MarkHenke2 Comments

We as software developers have created several disciplines for coding: test-driven developments, clean code principles, and screaming architecture, to name a few. However, we often find our web.config files can sprawl out of control. We just don’t pay as much attention to our configuration as we do to our classes and methods. The good news is that many mistakes are easily avoided, and with a little discipline we can put our configs on par with the rest of our codebase.

In this article, I’ll show you how. We’ll look at five of the most common configuration mistakes and how to avoid them.

(more…)

Spelling_Errors_Code_Written_in_Child_s_Blocks_Spelled_Wrong

Should You Hold Spelling Errors Against Developers?

Eric GoebelbeckerArticles, CodeQuality, CodeSpell, EricGoebelbecker, GhostDocNo Comments

You’re checking out some code. It’s been a long time since you looked at this project. Or maybe it’s the first time. You point your editor at an interesting file name and double-click to open it. Your coffee is warm, your mind is clear, and you’re ready to go.

And there it is, sticking out like white socks in sandals. A spelling error.

How do you handle it? Do you fix it? Do you ignore it? Discuss it with the author? Bring it up during lunch when he’s not around?

(more…)

Released: GhostDoc v2018

Serge BaranovskyGhostDoc, News, ReleasesNo Comments

Note to the GhostDoc v5 users: The v2018 requires a new license code. Users with License Protection or active Software Assurance subscription are eligible for a free upgrade. See the information at the bottom of this post for the details.

The v2018 release is packed with new and exciting features of which one particular is long awaited for – visual editing for XML comments – the feature that makes XML documentation authoring a breeze!

New features

  • Visual Editing for XML Comments
  • New menu and VS command – Document Project – now can generate XML Comment templates for a whole project
  • Support for C# 7.2 and VB 2017 syntax
  • The base web help documentation themes are now frameless. Original frame-based themes still shipped under new names
  • Support for Code Contracts when generating help documentation
  • Support for the <inheritdoc /> tag – in the XML Comments as well as the generated help documentation
  • Added VS IntelliSense file documentation output option
  • Added support for regular expression support in Dictionaries – Summary Override – enables flexible summary generation
  • New menu and VS command – Document File Header – allows generating/updating the file header without having to re-document the file
  • Improved performance of the Document File/Type batch actions
  • Introduced the Bug Bounty program – earn a license for helping us discover and fix bugs
  • Retired MS Help 2 documentation output format
  • GhostDoc Community edition now requires a one-time free Community License activation after 30 days of use
  • There are now two GhostDoc EULAs – Commercial License and Community License

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

To see new features by product edition see this page – http://submain.com/ghostdoc/editions/

Visual Editing for XML Comments

The number one challenge authoring XML comments, according to our users, has been ensuring a well-formed XML that includes encoding HTML formatting tags, code samples, etc. If that is not painful enough, many of malformed XML issues don’t even show up until the help docs are generated.

And now we offer a solution to this! Visual editing makes it painless to insert tables, lists, pictures, links, source code samples, and other formatting directly in your XML doc comments.

This is a huge leap from plain XML comment maintenance. Now you have WYSIWYG editing and don’t have to worry about valid and compliant XML in your comments. And there is no longer need to look up the correct syntax of the XML comment section tags and format to use.

The visual comment editor allows you to create and edit comments directly within an editable preview of the generated documentation. Comments created with the visual editor are written back to your source code in standard XML format, properly encoded, when required.

You still can have GhostDoc auto-generate your XML doc template in the Visual Editor, and then you have a Word-like experience to continue editing your documentation.

The new Visual Editor is such a great improvement – we also included it with the GhostDoc Community Edition!

Themes are now frameless

We have updated the web documentation themes with a modern frameless design. The new themes also allow for the help documentation search locally not requiring the server side active component. The older frame-based themes are still included for compatibility with the new names.

<inheritdoc /> tag

Instead of copying and syncing the base member XML Comment summary for a type member, using the <inheritdoc /> tag allows GhostDoc copying the documentation from base members into the final help documentation at the time the documentation is generated hence always rendering the latest copy of the base member docs.

Code Contracts

GhostDoc now will take your Code Contract XML Comment details and render them in the generated help documentation and Visual Editor. GhostDoc supports the following Code Contracts XML elements

  • <ensures />
  • <ensuresOnThrow />
  • <requires />
  • <invariant />
  • <pure />

To create the XML Comment tags for Code Contracts, we recommend using the CodeContracts tools for .NET

New output format – VS IntelliSense file

We added a new documentation output format – the IntelliSense file which is similar to that Visual Studio produces and GhostDoc users can also leverage of all the filtering built-in into the Build Help Documentation dialog as well as can generate it via the command line tool.

The VS IntelliSense format takes place of the MS Help 2 documentation output format that GhostDoc no longer supports.

Document Project and Document File Header

We must never say never – now GhostDoc has a new command to generate XML Comment templates for a whole project – Document Project.

Creating a file header used to be part of the Document File batch command and while it still is, we introduced the Document File Header command that allows generating and updating file header without having to re-document the whole file.

RegEx in Dictionaries – Summary Override

Using regular expressions can enable developers to do simple yet powerful things. Now you can use regular expressions in the Summary Override dictionary to improve the quality of the generated comment templates.

Here are two sample Summary Override entries:

New(?<pattern>(.|\n)*) - Creates new {pattern}.
To(?<pattern>(.|\n)*) - Converts to {pattern}.

These will create summary for NewCustomer as “Creates new Customer” and for ToModel as “Converts to Model”.

How do I try it?

Download the v2018 at http://submain.com/download/ghostdoc/

Feedback is what keeps us going!

Let us know what you think of the new version here – http://submain.com/support/feedback/

Older version licenses

Note to the GhostDoc v5 users: The v5.x license codes won’t work with the v2018. For users with License Protection and active Software Assurance subscription we have sent out the v2018 license codes. If you have not received or misplaced your new license, you can retrieve it on the My Account page. Users without the License Protection or with expired Software Assurance subscription will need to purchase the new version – currently we are not offering upgrade path other than the Software Assurance subscription. For information about the upgrade protection see our Software Assurance and Support – Renewal / Reinstatement Terms

Warning equals Error

Treat Warnings As Errors. I Mean It. You Need to Do This

Carlos SchultsArticles, CarlosSchults, CodeIt.Right, CodeQuality3 Comments

We here on the SubMain blog love to talk about programming best practices. Sometimes we’ll cover topics that are specific to C# or .NET as a whole. Other times, however, we write about concepts that are universal. Today’s post falls into the latter category. And I’ll start out by making a strong claim: you absolutely should treat warnings as errors when developing in .NET. Well, to be honest, that applies to virtually any platform.

The examples in this post, as usual, will be in the C# language. But as we’ve said, the concept applies pretty much everywhere.

(more…)

code_review_prep_runner_preparing_for_race

Code Review Prep: 4 Tips to Eliminate Inefficiency

Carlos SchultsArticles, CarlosSchults, CodeIt.Right, CodeQuality, CodeReviewsNo Comments

Code review is, hands down, one of the most fundamental best practices a software shop can employ to produce better software. A good code review practice can shed light on design problems, improve the readability of the code, and spread knowledge throughout a team. It also helps you find bugs early (when it costs less to fix them).

Code reviews sound like a gift from the heavens, right? While far from being a panacea, I’d say they are a spectacular tool to ensure software quality—when done correctly. And that, of course, is the tricky part. It doesn’t take much for a code review practice to go downhill. If you’ve been a developer for at least a few years, then I’d bet you have your share of scary stories to tell.

But that’s not what we’re here to talk about today. Forget the truly horrific stories—toxic workplaces and the like. Today we’re going to cover inefficiency in code reviews. Or, more precisely, we’ll offer you tips on how you can avoid it.

So, without further ado, let’s get to it: four tips that will help you when preparing to implement a code review practice in your software shop.

(more…)

Facepalm emoji over commenting fails

What Are the Biggest Code Commenting Fails You’ve Seen?

Sylvia FronczakArticles, CodeIt.Right, GhostDoc, SylviaFronczakNo Comments

We often focus on code fails. But what else have we seen and done that makes us drop our heads in shame and frustration? What else do we laugh (and cringe) at when reading code? The comments!

Whether they’re redundant, unreadable, confusing, or there’s just no comments at all, we can learn a lot from failure. And to spice things up, I’m going to throw in a biking analogy. You’re not sure if that’ll work? Me neither. But let’s go on this ride together and find out.

(more…)

Menu