Tag: C#

Comment and Document Updates for CI/CD

In reading about Continuous Integration/Continuous Deployment (CI/CD) I often find ways to manage the code, to get people around the code, to keep errors out of the code, and so on. It’s all about the code. Developers have, in fact, developed myriad ways to keep code size small, updated, deployed, tested, and so on to ensure that users have what they want, when the they want it (if not before). Sometimes my head spins on its axis after reading such documents because it becomes a high speed dizzying affair. It’s somehow assumed that everyone can just keep up. Except, there are new people and older people and people with lesser attention spans who can’t keep up, which is why comments and documentation are so important.

As part of the coding process, developers also need to update both comments and documentation or someone will come along and make modifications based on outdated information. Even though making such updates seems like a waste of time since everyone should be able to keep up, the truth is that these updates ultimately save time. However, the updates, when they occur (which apparently isn’t often) are often made in a haphazard manner reminiscent of an old Keystone Cops movie.

Adding a process, a workflow, to the CI/CD mill is important to ensure that everything remains in sync: code, comments, and documentation. A best practice way to accomplish this task is to add steps to every update process so that nothing is left behind. Here’s how you could approach the problem:

  1. Perform the required code updates.
  2. During testing, ensure that the comments within the code actually match what the code is doing. Testing and other review processes should not only look at the code, but the comments too.
  3. Update the documentation as final testing occurs. Make sure to include these elements:
    • Text
    • Drawings
    • Mockups
    • Visual Aids
    • Videos
    • Any other documentation elements
  4. Specify that any old comments/documentation are outdated using one of these approaches:
    • Mark it as deprecated
    • Remove it from the work area and put it in an archive
    • Delete it completely
  5. Deploy the application update. If you don’t deploy the update after these steps are done, they won’t get done. Everyone will wander off somewhere and forget all about any sort of comment or documentation update.

Obviously, the approach you end up using has to meet the requirements of your organization. It also has to be simple enough that people will actually, albeit begrudgingly, perform the work. What methods do you use to keep everything in sync at your organization? Let me know at [email protected].

Choosing a First Language to Learn

My first programming experience (during the time of the dinosaurs) involved using a light panel to enter machine code into a rudimentary computer with 3 KB (yes, that’s KB) of RAM. The output was also in light form and I needed to decode the lights to determine if my code worked right. I worked with various systems in various ways over the next several years. By the time I got to college, the first language I learned there was BASIC (Beginner’s All-purpose Symbolic Instruction Code), then PC assembler, followed by Pascal. In fact, I’ve just stopped counting the number of languages I’ve learned over the years because each language has a place in my programmer’s toolbox. Of course, the question is what language you should learn first. I get asked that question quite often because there are a huge number of languages available today and no one wants to invest time in a language that’s going nowhere.

Part of the answer to the question of what to learn first is what you intend to do with the language. Each language has features that make it better at performing specific tasks. Programming languages can be split into those that are designed for a special purpose and those that are designed for a general purpose. A special purpose language, such as Structured Query Language (SQL), could be a good choice if you intend to move into database work immediately. However, for most people, a general purpose language works better because you can use it for a wider variety of tasks without bending yourself into a pretzel shape to do it.

A good place to start if you want to choose a language that’s popular enough to help you get a job afterward is the TIOBE index. It shows a listing of which languages are most popular today. As I’m writing this, Python is the most popular language on the list, but that could change tomorrow. Generally, any of the top ten languages on the list are good choices.

Of course, you want a programming language that is easy to learn. C/C++, C#, and Java are all complex languages with great flexibility. Furthermore, C/C++ and C# can help you work at a low level with the computer hardware. These languages have a steep learning curve and may not provide the best choices for a starting point. That said, if you have a line on a job that uses any of these languages, you could do worse than start here, just be prepared to burn the midnight oil learning.

The language I suggest people learn as a starting point is Python. In fact, Beginning Programming with Python For Dummies, 3rd Edition makes a point of showing you just how easy things can be. You don’t even need to invest in any special software, the book shows you how to use Google Colab so that you could conceivably learn how to program on your smartphone or TV. Others must agree with me because Python has turned into the language that the education industry turns to most often for budding programmers.

There are a lot of programming languages available today. You need to research the choice by taking into account what your personal needs are and what sort of job you want to get afterwards. You might find that something like JavaScript or Ruby will provide benefits that you can’t get with Python. Which language do you think will work best for you? Let me know your reasons at [email protected].

Creating Sensible Error Trapping

This is an update of a post that originally appeared on May 23, 2011.

Errors in software happen. A file is missing on the hard drive or the user presses an unexpected key combination. There are errors of all shapes and sizes; expected and unexpected. The sources of errors are almost limitless. Some developers look at this vastness, become overwhelmed, and handle all errors the same way—by generating an ambiguous exception for absolutely every error that doesn’t help anyone solve anything. This is the worst case scenario that’s all too common in software today. I’ve talked with any number of people who have had to employ extreme effort just to figure the source of the exception out; many people simply give up and hope that someone has already discovered the source of the error.

At one time, error handling functionality in application development languages was so poor that it was possible to give the developer the benefit of a doubt. However, with the development tools that developers have at their disposal today, there is never a reason to provide an ambiguous “one size fits all” exception. For one thing, developers should make a distinction between the expected and the unexpected. Any expected error—a missing file for example—should be handled directly and specifically. If the application absolutely must have the file and can’t recreate it, then it should display a message saying which file is missing, where it is missing from, and possibly how to obtain another copy.

Even more than simply shoving the burden onto the user, however, modern applications have significantly more resources available for handling the error automatically. For example, it’s quite possible to use an Internet connection to access the vendor’s Web site and automatically download a missing application file. Except to tell the user what’s happening when the repair will take a few minutes, the application shouldn’t even bother the user with this particular kind of error—the repair should be automatic.

All of my essential programming books include at least mentions of error handling, debugging, exceptions, and other tasks associated with running code efficiently and smoothly. For example, Part IV of C++ All-In-One for Dummies, 4th Edition is devoted to the topic of debugging. Part V Chapter 3 of this same book talks about exceptions. If you’re a C# developer, C# 10.0 All-in-One for Dummies discusses exception handling in Book I Chapter 9. Book IV Chapter 2 discusses how to use the debugger to find errors. The point is that it’s essential to handle errors in your applications in a manner that makes sense to the users who rely on the application daily and the developers who maintain it.

Note that many of my newer books provide instructions for working with online IDEs, most especially Google Colab. These online IDEs rarely provide built-in debugging functionality, so then you need to resort to other means, such as those expressed in Debugging in Google Colab notebook.

Exceptional conditions do occur. However, even in these situations the developer must avoid the generic exception at all costs. If an application experiences an unexpected error and there isn’t any way to recover from it automatically, the user requires as much information as possible about the error in order to fix it. This means that the application should diagnose the problem as much as possible. Don’t tell the user that the application simply has to end—there is never a good reason to include this sort of message. Instead, tell the user that the application can’t locate a required resource and specify the resource in as much detail as possible. If possible, let the user fix the resource access problem and then retry access before you simply let the application die an ignoble death. Remember this! Any exception that your application displays means that you’ve failed as a developer to locate and repair the errors, so exceptions should be reserved for truly exceptional conditions.

Not everyone agrees with my approach to error trapping, but I have yet to hear a convincing argument to provide unreliable, non-specific error trapping in an application. Poor error trapping always translates into increased user dissatisfaction, increased support costs, and a reduction in profitability. Let me know your thoughts on the issue of creating a sensible error trapping strategy at [email protected].

Creating Useful Comments

This is an update of a post that originally appeared on November 21, 2011.

A major problem with most applications today is that they lack useful comments. It’s impossible for anyone to truly understand how an application works unless the developer provides comments at the time the code is written. In fact, this issue extends to the developer. A month after someone writes an application, it’s possible to forget the important details about it. In fact, for some of us, the interval between writing and forgetting is even shorter. Despite my best efforts and those of many other authors, many online examples lack any comments whatsoever, making them nearly useless to anyone who lacks time to run the application through a debugger to discover how it works.

Good application code comments help developers of all stripes in a number of ways. As a minimum, the comments you provide as part of your application code provides these benefits.

  • Debugging: It’s easier to debug an application that has good comments because the comments help the person performing the debugging understand how the developer envisioned the application working.
  • Updating: Anyone who has tried to update an application that lacks comments knows the pain of trying to figure out the best way to do it. Often, an update introduces new bugs because the person performing the update doesn’t understand how to interact with the original code.
  • Documentation: Modern IDEs often provide a means of automatically generating application documentation based on the developer comments. Good comments significantly reduce the work required to create documentation and sometimes eliminate it altogether.
  • Technique Description: You get a brainstorm in the middle of the night and try it in your code the next day. It works! Comments help you preserve the brainstorm that you won’t get back later no matter how hard you try. The technique you use today could also solve problems in future applications, but the technique may become unavailable unless you document it.
  • Problem Resolution: Code often takes a circuitous route to accomplish a task because the direct path will result in failure. Unless you document your reasons for using a less direct route, an update could cause problems by removing the safeguards you’ve provided.
  • Performance Tuning: Good comments help anyone tuning the application understand where performance changes could end up causing the application to run more slowly or not at all. A lot of performance improvements end up hurting the user, the data, or the application because the person tuning the application didn’t have proper comments for making the adjustments.

The need for good comments means creating a comment that has the substance required for someone to understand and use it. Unfortunately, it’s sometimes hard to determine what a good comment contains in the moment because you already know what the code does and how it does it. Consequently, having a guide as to what to write is helpful. When writing a comment, ask yourself these questions:

  • Who is affected by the code?
  • What is the code supposed to do?
  • When is the code supposed to perform this task?
  • Where does the code obtain resources needed to perform the task?
  • Why did the developer use a particular technique to write the code?
  • How does the code accomplish the task without causing problems with other applications or system resources?

There are many other questions you could ask yourself, but these six questions are a good start. You won’t answer every question for every last piece of code in the application because sometimes a question isn’t pertinent. As you work through your code and gain experience, start writing down questions you find yourself asking. Good answers to aggravating questions produce superior comments. Whenever you pull your hair out trying to figure out someone’s code, especially your own, remember that a comment could have saved you time, frustration, and effort. What is your take on comments? Let me know at [email protected].

Checking SQL Server Status

This is an update of a post that originally appeared on November 14, 2012.

A number of my books rely on database access. Today that database access can take many forms, such as the use of .csv files in my AI, machine learning, and deep learning books. However, this post is specific to those books that use Microsoft’s SQL Server on the local system, which is currently limited to C++ All-In-One for Dummies, 4th Edition (optionally) and C# 10.0 All-in-One for Dummies, but could include other books in the future (or you may simply decide to use Microsoft SQL Server with one of my other books).

In order to access any server, the server must be running. It only makes sense that you can’t access something that isn’t listening. The problem is that SQL Server may not start automatically for a number of reasons on your system and that Visual Studio doesn’t always make it apparent that the server isn’t running. You may get a nebulous message when you try to make a connection that doesn’t tell you anything. (No, SQL Server doesn’t start automatically when you make a request for data.) With this in mind, a post of checking the status of SQL Server is important.

Normally, I would tell you to use the tools that come with SQL Server to check the status of the server. However, some versions of SQL Server Express Edition install without the standard tools now, such as SQL Server Management Studio (SSMS). Without access to these tools, it may seem as if checking the server status is impossible. Fortunately, you have other options.

The best way to check the status of SQL Server on your system is to use the Services console found in the Administrative Tools folder of the Control Panel. The Services console is one of a number of Microsoft Management Console (MMC) snap-ins that Windows installs automatically for you. However, to use this console, you must have administrator rights on the target system. Without these rights, you truly are out of luck in checking the status of your SQL Server setup and will need to get an administrator to help you.

Open the Services console by right clicking Start, choosing Run from the menu, typing services.msc in the Open field, and clicking OK. You find a list of all of the services installed on your system in the resulting Services window. Scroll down the list and you should find one or more SQL Server entries like the ones shown here.

The services window contains a list of Windows services installed on the local machine that their status.
Use the Services console to check the status of services on your system.

In order to work successfully with the examples in my book, you should have SQL Server set to start automatically. In addition, when you check the service, you should see Started in the Status column as shown in the screenshot. If you don’t see Started, then highlight the service as shown and click the Start link you see on the left side (not shown in this case because the service is already started).

To make the examples easier to work with, you should also ensure that the SQL Server Browser service is started. This service makes it possible for Visual Studio to find the SQL Server installation on your system. Without this service, you must correctly type the name of the SQL Server installation you want to use when creating a connection, which is both time consuming and error prone.

If you find that you encounter problems making database examples in my books work, please check the status of SQL Server to ensure the service is actually started. Contact me at [email protected] if you experience any other connectivity problems. I may not be able to fix every problem you encounter, but I often have a good idea of what problems you might be seeing on your system and will do my best to help you.

Web Page Units of Measure

This is an update of a post that originally appeared on October 23, 2013.

There are ways today of avoiding any thought of what units of measure the Web page you’re working on uses. For example, I use products like WordPress all the time now to make the task of creating content quickly a lot easier. I don’t ever think about the units of measure I’m using when working with these products. However, when designing an interface for an Android or C# application (as examples), I sometimes do need to think about units of measure because I’m more intimately involved in the user interface design process. Today, applications need to work everywhere on a large number of devices, all of which have different characteristics, so units of measure can become an issue. So, it’s entirely possible that you could create a nearly unlimited amount of content for a website without ever worrying about units of measure, but this blog post is for those times when it does matter.

Some units of measure work better than others do in obtaining a specific result. For example, when you specify placement in pixels (px), you tell the browser to define element placement with regard to the physical units of a display. This is the most precise, yet least flexible, method of defining units of measure. In addition, it can create issues with mobile devices because these devices typically don’t offer that many pixels of display area and may not allow scrolling of information that doesn’t appear in a single screen (the part that appears to the right and toward the bottom of the page).

More flexible units of device-specific measure include the inch (in), centimeter (cm), and millimeter (mm). In this case, the browser converts the measurement to pixels using the device’s conversion metric. For example, a typical PC display uses 96 pixels-per-inch. However, the user can change the metric so that an inch could consume 120 pixels instead (making the elements larger than normal). Whether this flexibility solves the problem of working with mobile devices depends on the mobile device and the metric it uses to convert physical units to pixels.

Besides device and physical measures, you can also use printer’s measures that include the point (pt) and pica (pc). These units of measure theoretically work the same as physical measures because a point is 1/72nd inch and a pica is 12 points (or 1/6th inch). In reality, it’s possible that a browser will convert the units of measure based on the size of the fonts that the device uses. However, you can’t count on this flexibility and must assume that these printer’s measures are simply a different kind of physical measure.

Fortunately there are two units of measure that are guaranteed to reflect the size of a font on the display. The em is a measure of the actual font size. One device may use a 12 point font while another device uses a 10 point font. An em will equal 12 points on the first device and 10 points on the second device without any modification of the code on your part. This feature makes the page quite flexible and usable with any device. The other unit of measure is the ex, which is the measure of the x-height of a font (the median of all of the characters in a particular letter set). As with the em, the ex automatically scales to consider the point size of characters used by a particular device.

All of the units of measure so far are absolute. You place elements on a screen in a precise position. Modern Web design dictates that pages employ Responsive Web Design (RWD) to ensure that the page will work on any device. A part of RWD is to use relative placement wherever possible so that the page and its elements automatically resize to meet the needs of a device. You use the percentage (%) unit of measure in this case, where an element uses a percentage of the available space, whatever that space might be. Of course, this approach means that all devices see the entire page. However, a disadvantage of this approach is that the elements might be so small on some devices as to make them unusable.

The article, CSS values and units, provides you with more information about units of measure as they apply to Cascading Style Sheets (CSS). These guidelines generally apply to other working environments as well. What are your thoughts about units of measure? Which do you use most often? Let me know at [email protected].

Choosing Variable Names

This is an update of a post that originally appeared on January 17, 2014.

It often surprises me that developers seem to choose completely useless variable names like MyVariable when creating an application. Although MyVariable could be an interesting variable name for an example in a book, it never has a place in any sort of production code. Even then, I try to create book examples with meaningful variable names, especially when getting past the initial “Hello World” example. Variable names are important because they tell others:

  • What sort of information the variable stores
  • When the variable is commonly used
  • Where the variable is used
  • How to use the variable correctly
  • Why the variable is important

In some cases, the variable name could even indicate who created the variable; although, this sort of information is extremely rare. If you never thought a variable name should contain all that information, then perhaps you haven’t been choosing the best variable names for your application.

Even with these restrictions in place, choosing a variable name can be uncommonly hard if you want to maximize the name’s value to both yourself and other developers. Some organizations make the selection process easier by following certain conventions. If you don’t have an organizational style guide for variable naming, modern programming languages like Python commonly provide a style guide for you to use. These style guides often consider a great deal more than simply variable naming and include issues like the amount of indentation to use. In some respects, they become quite draconian in their approach. Other style guides, like the one for C#, are less time consuming to learn, which is a good thing because most developers have better things to do with their time than to learn some of these nitpicky details. A few languages suffer from an abundance of style guides, like C++. It’s best to choose one of them, such as the Google C++ Style Guide, and stick with it.

However, let’s say that you want to create your own style guide for your organization to use because you use multiple languages and having a different style guide for each language seems just a bit absurd, not to mention adding needless complexity. In this case, you need to ask yourself a series of questions to determine how you want the style guide to work, such as these:

  1. What sort of casing do you want to use for what types of variables?
  2. What information does the variable contain (such as a list of names)?
  3. How is the variable used (such as locally or globally, or to contain coordinates, or a special kind of object)?
  4. When appropriate, what kind of information does the variable contain (such as a string or the coordinate of a pixel on screen)?
  5. Is the variable used for a special task (such as data conversion)?
  6. What case should prefixes, suffixes, and other naming elements appear in when a language is case sensitive?

The point is that you need to choose variable names with care so that you know what they mean later. Carefully chosen variable names make it possible for you to read your code with greater ease and locate bugs a lot faster. They also make it easier for others to understand your code and for you to remember what the code does months after you’ve written it. However, most important of all, useful variable names help you see immediately that a variable is being using the wrong way, such as assigning the length of a name string to a coordinate position on screen (even though both variables are integer values). Let me know your thoughts about variable naming at [email protected].

Antiquated Technology Making Developers Faster

This is an update of a post that originally appeared on November 7, 2014.

I often wonder when I create a blog post whether the technology I’m describing will stand the test of time. In this case, I asked whether the reader would like to be able to type application code faster and with fewer keystrokes. The article, The 100 Year Old Trick to Writing at 240 Words Per Minute, probably has some good advice for you—at least, if you’re willing to learn the technique. It turns out that stenography isn’t only useful for court typists and people who print out the text for the hearing impaired on television, it’s also quite useful for developer. Yes, your IDE probably has more than a few tricks available for speeding up your typing, but I guarantee that these tricks only go so far. My personal best typing speed is 110 wpm and that’s flat out typing as fast as my fingers will go.

Since that original post, someone has come out with a book called Learn Plover! that describes how to use this stenographic technique in more detail. There is also a site devoted to Plover now.

Naturally, I haven’t ever used one of the devices mentioned in the article. However, a stenographer named Mirabai Knight has tried one of the devices and reproduced a 140 keystroke Python application using only 50 keystrokes. By the way, she has produced a series of interesting videos that you may want to review if you really think that Plover is for you. I don’t know of any IDE that can provide that sort of efficiency. Of course, it’s one thing for a trained stenographer to produce these sorts of results, but I’d like to hear from any developer who has used the technique to hear about how well it worked for them. Please contact me about your experiences at [email protected]. (Oddly enough, I did hear from at least one developer who uses it successfully.)

The part that interested me most though is that the system, called Plover, is written in Python. (If you want to see Plover in action, check out the video at http://plover.stenoknight.com/2014/10/longer-plover-coding-snippet-in-python.html. A number of Beginning Programming with Python For Dummies, 3rd Edition readers have written to ask me how they can use their new found programming skills. The book contains sections that tell you about all sorts of ways in which Python is being used, but many of these uses are in large corporations. This particular use is by a small developer—someone just like you. Yet, it has a big potential for impacting how developers work. Just imagine the look on the boss’ face when you turn in your application in half the time because you can type it in so much faster? So, Python isn’t just for really large companies or for scientists—it’s for everyone who needs a language that can help them create useful applications of the sort that Python is best suited to target (and I describe all of these uses in my book).