SubMain.com
YouTube
RSS

Articles

Home Category: Articles (Page 9)
In today's post on hungarian notation, we look at why it wound up looking like this toe-tagged body at the morgue.

Hungarian Notation Postmortem: What Went Wrong?

Rick Beley27 Comments

Is Hungarian notation really adjDead? Suggesting a postmortem might be a bit premature, but it could be fun to take a quick dive into what we?ve learned from a really smart Hungarian named Charles Simonyi who tried to find a better way. Anyone who tries to bring some clarity to the chaos they find in their everyday dealings has a lot in common with us developers. Mr. Simonyi is one of us. Let?s hear him out!

What Is Hungarian Notation?

Hungarian notation is one of those topics of great debate in the programming community. You can find just as many intelligent and well-respected proponents as you can find opponents. Likewise, you can find lists about its positive contributions, and you can read articles on why it should never surface. As with most of these more philosophical debates, I find myself stuck in the middle. And when that happens, I find great value in hearing out those with strong opinions about it.

To a non-developer, computer code can appear rather ambiguous and obscure. To a developer, someone else?s computer code can be the same when we fail to be united in our approach. If you?ve spent any amount of time hacking away at a keyboard, writing complex computer instructions, I?m sure you?ll understand the concepts behind Hungarian notation. Mr. Simonyi is simply trying to bring some clarity to the language you?re using with your computer.

How Does It Work?

So, what is Hungarian notation and how does it work? To sum it up, Hungarian notation is a systematic approach to naming variables in our programs, using the type and a given name, in that order. If ?lastName? is a string, think strLastname for its Hungarian notation. Consider this block of pseudocode:

string ln= ?Simonyi?;
string fn= ?Charles?;
string dn= ln + ?,? + fn;
int len = dn.length();

It?s a pretty simple piece of code with a few string variables and an integer. Come on a quick journey with me; let’s say this was line 444 through 448 in 1000+ lines of code. The variable names tell us very little about what we?re storing in them. And when the variable is referenced further down in the code, we may find ourselves scrolling back up to find out what it means. If we used Hungarian notation, along with some better variable names, maybe we?d see something like this:

string sLastname = ?Simonyi?;
string sFirstname = ?Charles?;
string sDisplayname = sLastname + ?,? + sFirstname;
int nLength= sDisplayname .length();

You?ll notice right away that the variable names are clear, their intents and purposes are solidified, and they?re prepended with the correct type (s for string, n for integer). No more guessing, and no more scrolling back to check the type.

That?s it.

Yup, that?s the basic idea behind Hungarian notation. And you can find article after article, opinion piece after opinion piece, and plenty debate all throughout the internets about it.

(more…)

CodeIt.Right Rules Explained, Part 12

CodeIt.Right Rules Explained, Part 12

Erik Dietrich1 Comment

This week, we bring you another post in the CodeIt.Right Rules Explained series.? In case this is new for you, with each post in the series, I take you through three CodeIt.Right?rules in detail.? CodeIt.Right is an automated code review tool, making use of static code analysis.

As I always do with these posts, I’ll start with two solid rules of thumb for static analysis.

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

And, as I always do, I’ll explain that I don’t phrase it this way to play some sort of game.? You might wonder why I don’t just tell you to learn every suggested fix and call it a day.

Well, I phrase it this way to make it clear that you face a specific choice each and every time you encounter an analysis warning: fix it or ignore it.? And when you make that choice, you should make it for the right reasons.? “I don’t know what this means,” isn’t the right reason.? I also approach it this way because trying to learn?all?of the rules at once would prove extremely daunting.

So let’s dive deep into understanding another three rules today.

(more…)

Reducing software risk can be like a game of chess.

5 Low-Impact Strategies to Reduce Software Risk

Erik Dietrich1 Comment

When you’re learning the game of software development, you probably never think of software risk.? You write a few lines of code, then you celebrate seeing “Hello World” on the screen.? Rinse, repeat as you build ever more impressive stuff, teaching yourself the craft.

What risk?

But then you take a job doing this stuff, and that changes in a hurry.? Sure, it’s mostly organizational leadership that tosses around the term “software risk” in meetings and looks to quantify it.? But anyone with skin in the game feels the weight of risk acutely.? What if the user types in something we don’t expect?? What if the release doesn’t go well?? Will we get frantic calls at 3 AM about this?

When commerce depends on the software that you write, the possibilities for problems seem endless.? Risk is everywhere.

What is Risk?

Before we look at how to reduce risk, let’s take a crack at meaningfully defining it. In the world of commerce or investment, risk refers to the possibility of an investment losing value.? And while that’s somewhat applicable to the commercial world in which software resides, we need to generalize a bit.? Let’s take this definition from the dictionary to cover our bases:

Someone or something that creates or suggests a hazard.

Truly, this is what we mean when we talk about software risk.? Sure, hazardous production behavior of the software might result in financial damages to your company.? If you view the software as a commodity (which I don’t really recommend), you could even say that the presence of defects reduces its value.? But the investment definition fits awkwardly.? Really, we’re talking about?hazard.

Software is?really complicated.? We build this stuff, reason about it the best we can, test it out, then send it to production like an ocean liner on its maiden voyage.? And when it gets to that metaphorical ocean, a lot of unexpected things can go dramatically wrong.? We talk about this as risk.

Defining Low Impact

Of course, we’re not helpless.? As software development shops, we can do a lot to mitigate this risk, and we frequently do.? Here are some common suggestions that you’ll hear:

  • Get a good, robust, automated test suite in place.
  • Ramp up exploratory QA and load/stress testing efforts.
  • Break the code apart into more isolated, decoupled microservices.
  • Switch methodology and “go agile.” (Or go the other direction and plan harder)
  • Hire experts to come in for an assessment.

Everything there can absolutely help.? But if you’re working in a lot of small-to-medium-sized shops, these things tend also to be pipe dreams: “Oh, sure, we’ll just tell our customers to wait a while and put in a bunch of tests, go agile, and refactor the whole application.? And when we’re done with that, we’ll get to work on building that morale-boosting waterslide from the third floor to the first floor, too.”

So instead of the traditional approaches that require significant investment and the overhaul of your current approach, let’s look at some relatively low-impact things you can do.? While these require time investment and behavior changes, all of them are things you can do with relatively minor cash investment and relatively minimal disruption to your general work.

(more…)

An entire large team arguing over the coding standard.

What’s Your Worst Experience with a Coding Standard?

Erik Dietrich9 Comments

I remember the first time I encountered GhostDoc.? It was an oasis in a professional desert of soul-sucking conformity.

Okay, wait. Let me back up and explain.

I was working in a custom app dev shop at the time.? While working there, I worked on an assortment of apps, big and small, and I delivered to an assortment?of clients, big and small.? Some had their own internal maintenance devs, and some did not.? And yet, in spite of this disjoint, hodgepodge arrangement, the company maintained a single?and relatively?involved coding standard for dozens of folks on dozens of projects.

The “Professional” Coding Standard

Most aspects of the standard were unremarkable and understandable.? So, on the whole, this didn’t bother me.? But there was an edict floating around in there that said every method and class, no matter what, needed XML doc comments.

This applied to code being maintained by client developers and to code that nobody would ever look at again.? It applied to both API deliverables and to GUI crud apps that nobody would touch again.? Why comment everything in this fashion, no matter what?? Because it makes us “look professional,” that’s why.

Ugh.

And so I found myself laboriously going back and brainlessly adding comments to dozens of files.? You see, I hadn’t known about this standard when I started, so I didn’t bother commenting this forms-over-data thing for which we weren’t even delivering source code.? So I had a lot of “work” to do.

Initially, I contemplated writing my own commenting engine.? I honestly think I could have done that in less time than it would take to hand comment.? But then I figured something like this had to exist already, and my search led me quickly to GhostDoc.

Once I discovered that, I sprayed my code with comments like an exterminator taking care of an ant problem.? Then I called it a day.

As I’ve discussed previously, this is NOT how I’d use GhostDoc today or how I’d approach commenting in general.? But it got the “job” done, and the powers that be considered “my” comments completely acceptable.? Project finished.

(more…)

CodeIt.Right Rules Explained, Part 11

Erik DietrichNo Comments

It’s time for another post in the CodeIt.Right Rules Explained series.? I daresay it’s becoming a pretty predictable post series, with a pretty predictable cadence.? And that’s a good thing!? CodeIt.Right offers automated code review, and this series of blog posts gives you a detailed tour of the what and also the why of the code review rules.

As has become custom, I’ll start with two solid rules of thumb for static analysis.

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

Every month, I explain that I don’t phrase it this way to play some sort of game.? After all, I could just declare that everyone should learn every suggested rule and be done with it.? But I phrase it this way to make it clear that you face a specific choice each and every time you encounter an analysis warning: fix it or ignore it.? And when you make that choice, you should make it for the right reasons.? “I don’t know what this means,” isn’t the right reason.

So let’s dive deep into understanding another three rules today.

(more…)

You don't need a code review template like the one shown here.

You Don?t Need a Code Review Template

Erik Dietrich1 Comment

What do you have in mind when you search or hope for a code review template?? I’ll bet I can guess.

You’re looking for something to guide you through the process.? In your mind, this probably takes the form of a worksheet of some kind.? The appropriate document should have a checklist of items for you to tick off and perhaps some free-form text spaces for you to make notes.? It will also guide you through the process in general.

I get it.? But you really don’t need this, even though it seems perfectly reasonable and inviting.

The Actual Life of a Code Review Template

Before I dive into the meat of?why you don’t need this document, let me talk about what will happen to it when you acquire it.

First, you’ll go searching and find something like this.? Then you’ll find a few more of those and put it together into your own list.? It will include items like the following:

  • Each method should have a clear responsibility.
  • Each method should also have no more than three parameters.
  • Close any connections you open and dispose of any resources that need disposing.

And so on.

You’ll put this document together, and then you’ll stick it on your group’s SharePoint site, where everyone can see it and add to it if need be.? “It’s a living document,” you’ll assure everyone.

Your brand-new code review process will get off to a good start, with people participating and faithfully following the code review template.? They’ll check the checkboxes, fill out the text for the questions, and generate adjustments to the code where needed.? For a while, anyway.

But where you’d eventually expect the efficiency of these reviews to improve, the opposite happens.? The document grows. Code reviews get longer and more mind-numbing, and people start to hate them.? Then, they start to?avoid them altogether, when possible.? The group’s collective dissatisfaction eventually leads to an overhaul of the process.

And the code review template sits there on SharePoint, untouched, like a digital fossil.

(more…)

Different tool vendors can help you automate API documentation.

How Do You Handle API Documentation?

Erik Dietrich1 Comment

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

CodeIt.Right Rules Explained, Part 10

Erik Dietrich1 Comment

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

A Field Guide to Code Comments

Erik Dietrich9 Comments

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…)

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

Code Documentation and Code Comments Aren?t the Same Thing

Erik Dietrich1 Comment

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.

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…)

Menu