Tag: Python

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].

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].

Python Used for Common User Interface Needs

This is an update of a post that originally appeared on September 12, 2014.

Beginning Programming with Python For Dummies, 3rd Edition describes how to start working with Python. You discover how to perform all the basics and I provide a few real world examples. However, once you’re done with the book, you might ask how Python can be used for real world programming of the sort that you need to do. One of the most common tasks is creating a user interface. Just about every application out there requires a user interface and it has become popular to make user interfaces touchable. Fortunately, Python developers have access to a huge number of libraries to make seemingly hard tasks simple. In fact, that’s one of the advantages of using Python—the immense number of really practical and useful libraries at your disposal. It’s possible to find a library for just about any need.

One of the more interesting libraries available for Python is Kivy. This library makes it possible to create multitouch applications without having to do all the heavy lifting yourself. The interesting thing about using Kivy for this task is that it helps you avoid some of the problems with other sort of multitouch application environments, such as using a combination of HTML5, CSS3, and JavaScript (where a less than compatible browser can ruin your chances of making the application work properly). This is a native code library that works on the Linux, Windows, OS X, Android and iOS platforms, so you have a good chance of finding precisely the support you need in a package that will perform well on the chosen platforms. Like all Python applications, the application you create on the Mac will work just fine on Windows too.

Of course, there are tons of libraries for Python, so why did I choose to talk about this particular library? It turns out that Kivy is proactive about obtaining as much developer support as possible. I’ll admit it, I was bedazzled looking at all the eye candy on this site. What I thought was a five minute scan of the example applications turned out to be more than an hour of perusing what’s possible with Kivy and Python. All you need to do to try one of the applications out is to click its link, download the code, and start running it. Nothing could be easier (or time consuming as it turns out). Soon, you’ll find your days consumed by checking out Kivy applications too.

Fortunately, Kivy is also free. All you need to do is download the copy for your platform and install it. So, you get this great library that you can use for your business applications and it doesn’t cost you a dime. What I’d most like to hear about is whether someone is using Kivy in a large scale business application and how its performing for them. Speed is always an issue with Python, despite all the other amazing features it provides, so finding libraries that use every bit of speed Python has to offer is essential.

I take a lot of time looking for various tools, libraries, applications, and other resources for readers to use with my books. I’m not looking for anything cheesy, crippled, or difficult to use—I want well written, popular, and preferably free resources I can share. If you are a developer who is using an outstanding library or tool that specifically meets the needs of my readers, please let me know about it at [email protected]. Please, no vendors! I want to hear from people not associated with an organization who are actually using the tool or library in question for development purposes.

Python Community Support

This is an update of a post that originally appeared on October 13, 2014.

There are many issues to consider when choosing a programming language. Python is no exception. Just because I feel it’s the right tool to meet some of my needs doesn’t mean it will work well for you. That’s why the Understanding Why Python is So Cool section of Chapter 1 in Beginning Programming with Python For Dummies, 3rd Edition is so important. This section tells you why I see Python as an important programming language and why you might want to use it too. I break the problem into three parts: what Python can do for your application needs, how Python can benefit you personally, and which organizations are using Python for specific tasks. Between the three sections, you can make an intelligent decision as to whether Python will actually serve your particular needs. I really don’t want you to take my word for it—I would rather know that you selected Python based on your own research.

No matter how interesting a language is, no matter how many features it provides, and no matter how much you personally like it—you can’t typically learn a language that lacks broad community support with any ease. If no one else is using the language and contributing to it in some major way, the language will eventually die. Fortunately, Python doesn’t have this problem. Chapter 21 of my book discusses ten essential libraries for Python, none of which come with the language when you download it. In fact, the introduction to this chapter lists a number of places where you can find even more libraries to use.

The thing is that Python keeps attracting ever more attention. A recent Dev article, 10 Best Tools Python Programmers Can Learn in 2023, provides you with access to tools you really need to know about. The point about tools is that they represent an essential form of community support. As people use a language, they start to build places where others can discuss it with them. However, that’s only one form of community support. Tools represent a significant increase in support because creating, debugging, and supporting a tool requires time and effort that most developers don’t have in abundance. Someone really has to believe in a language to provide this sort of language support.

The fact is that Python has become a “must learn” language. It has great community support, provides a broad range of functionality through libraries and tools, and is fully supported by the academic community. Even though other languages have had these advantages and eventually failed, the chances are far less likely that Python will experience problems. In fact, many rankings sites show Python as being the most popular language out there right now.

Community support is an essential determinant of programming language popularity. How do you rank Python in your toolbox and why? Let me know at [email protected]. Tell me about your favorite Python library or tool and how you use it as well. (No vendor emails please, I want to hear from developers who are actually using products.) I’m interested in discovering just what makes some languages so incredibly popular (Python being one of the most popular).

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

Understanding the Continuing Need for C++

This is an update of a post that originally appeared on February 23, 2015.

I maintain statistics on all my books, including C++ All-In-One for Dummies, 4th Edition. These statistics are based on reader e-mail and other sources of input that I get. I even take the comments on Amazon.com into account. One of the most common C++ questions I get (not the most common, but it’s up there) is why someone would want to use the language in the first place. It’s true, C++ isn’t the language to use if you’re creating a database application and schools now prefer Python as an introductory programming language for older children. However, it is the language to use if you’re writing low-level code that has to run fast. C++ also sees use in a vast number of libraries because library code has to be fast. For example, check out the Python libraries at some point and you’ll find C++ staring back at you. In fact, part of the Python documentation discusses how to use C++ to create extensions.

I decided to look through some of my past notes to see if there was some succinct discussion of just why C++ is a useful language for the average developer to know. That’s when I ran across an InfoWorld article entitled, “Stroustrup: Why the 35-year-old C++ still dominates ‘real’ dev.” Given that the guy being interviewed is Bjarne Stroustrup, the inventor of C++, it’s a great source of information. The interview is revealing because it’s obvious that Bjarne is taking a measured view of C++ and not simply telling everyone to use it for every occasion (quite the contrary, in fact).

The bottom line in C++ development is speed. Along with speed, you also get flexibility and great access to the hardware. As with anything, you pay a price for getting these features. In the case of C++, you’ll experience increased development time, greater complexity, and more difficulty in locating bugs. Some people are taking a new route to C++ speed though and that’s to write their code in one language and move it to C++ from there. For example, some Python developers are now cross-compiling their code into C++ to gain a speed advantage. You can read about it in the InfoWorld article entitled, Python to C converter tool.

A lot of readers will close a message to me asking whether there is a single language they can learn to do everything well. Unfortunately, there isn’t any such language and given the nature of computer languages, I doubt there ever will be. Every language has a niche for which it’s indispensable. The smart developer has a toolbox full of languages suited for every job the developer intends to tackle.

Do you find that you really don’t understand how the languages in my books can help you? Let me know your book-specific language questions at [email protected]. It’s always my goal that you understand how the material you’ve learned while reading one of my books will eventually help you in the long run. After all, what’s the point of reading a book that doesn’t help you in some material way? Thanks, as always, for your staunch support of my writing efforts!

IPython Magic Functions

This is an update of a post that originally appeared on April 25, 2016.

All of my current Python language books (and those I collaborated on with Luca Massaron): Machine Learning Security Principles, Algorithms for Dummies, 2nd Edition, Beginning Programming with Python For Dummies, 3rd Edition, Python for Data Science for Dummies, and Machine Learning for Dummies, 2nd Edition allow use of Jupyter Notebook (through Anaconda) or Google Colab to interact with the example code. Both of these IDEs extend the development environment in a number of ways, one of which is the use of magic functions. You see the magic functions in the code of these books as calls that begin with either one or two percent signs (% or %%). The most common of these magic functions is %matplotlib, which controls how IPython Notebook or Jupyter Notebook display plot output from the code.

You can find a listing of the most common magic functions in the Python for Data Science for Dummies Cheat Sheet. None of my books use any other magic functions, so this is also a complete list of magic functions that you can expect to find in our books. However, you might want to know more. Fortunately, the site at https://damontallen.github.io/IPython-quick-ref-sheets/ provides you with a complete listing of the magic commands (and a wealth of other information about Jupyter Notebook).

There are differences in magic function support between Jupyter Notebook and Google Colab, some of which are outlined in our books as needed. None of these differences will significantly affect your learning experience. However, it pays to know that Jupyter Notebook and Google Colab are only mostly the same, not precisely the same, and you’ll encounter differences. The screenshots in my books reflect the Jupyter Notebook version supported by that book, so what you might see on your screen when using magic functions in Google Colab may differ from the book.

Of course, you might choose to use another IDE—one that isn’t quite so magical as Jupyter Notebook or Google Colab. In this case, you need to remove those magic commands. Removing the commands generally won’t affect functionality of the code. The example will still work as explained in the book. However, the way that the IDE presents output could change. For example, instead of being inline, plots could appear in a separate window. Even though using a separate window is less convenient, either method works just fine. If you ever do encounter a magic function-related problem, please be sure to let me know at [email protected].