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

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

Sending Comments on My Books

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

I regularly receive a stack of e-mail about my books. Readers question everything and it makes me happy to see that they’re reviewing my books so closely. It means that I’m accomplishing my principle goal, helping you understand computers in every possible way so that you can be more productive and accomplish tasks with less effort. When I make something easier for someone and they tell me about it, the grin extends from one side of my face to another. It really makes my day.

Some readers are still asking me if it’s OK to send me comments. I definitely want to see any constructive comment that you have. Anything that helps me understand your needs better makes it possible for me to write better books. I really do want to hear from you. The main element that I need to obtain a usable comment is that it’s constructive. A comment that lacks details isn’t helpful because I’ve written so many books. Emotional comments without any substance are especially hard to deal with because they leave me wondering what you need from me. Here are some of the things you can do to create a constructive comment:

  • What is the title of the book you’re reading (be sure to include the edition number, which is usually right on the cover unless it’s a first edition)?
  • Are you using the downloadable source code if this is a programming book?
  • Did you install the recommended version of any required software using the instructions found in the book?
  • Which page contains the error (if you’re using Kindle or other electronic media, please provide a chapter number and section title as a minimum)?
  • What do you view as an error on that page?
  • How would you fix the error?
  • What sort of system are you running?
  • When did you encounter the problem?

The more information you provide, the easier it is for me to understand the issue and provide you with feedback. In many cases, I’ll upload the fix to my blog so that everyone can benefit from the response (so be sure you keep an eye on my blog for new entries). I work hard to ensure that my books are as error free as possible, but everyone makes mistakes. Also remember that sometimes mitigating factors, such as differences in software versions or anticipated hardware, make it appear that there is an error in the book when you’re really looking at a different in environment. Help me provide you with better books—send me comments!

There are a few things that I won’t do for you. I won’t help you pass an exam at school. Your learning experience is important to me, which means that I want you to continue your education by working through the instruction on your own. I also don’t provide free consulting. This means I won’t check the code that you created on your own for errors. In addition, if you don’t use the downloadable source, be sure to read Verifying Your Hand Typed Code for restrictions on the level of support that I provide. I’ll help you with any book-specific question, but I draw the line at that point. Let me know if you have any input or insights on my books at [email protected].

Getting the Fastest Question Response

I always want to be sure that you get fast, courteous responses to your book-specific questions. Even though I don’t check my e-mail every day, I do check it most days of the week, so that’s the fastest way to contact me regarding issues that you have with my books. Of course, you can make the response even faster by doing a few simple things when sending your email:

  • Be sure to include the name of the book and the book edition in the message subject line.
  • Tell me which page, figure, or listing number to look at in the book.
  • Document the steps you took.
  • Provide me with the exact error message you’re seeing.
  • Tell me about your platform (operating system, the version of any software you’re using, and so on).

If you provide these basic pieces of information, I can usually answer your questions much faster—often without asking for additional information. E-mail communication can be difficult at times because it lacks that in person body language element and you can’t show me what you’re seeing on your machine. Remote diagnostics are harder than you might think.

It’s also important that you understand that I focus on book-specific questions. I’ve discussed this issue before in Sending Comments on My Books and Sending Comments and Asking Questions. The bottom line is that I want you to be happy with your book experience, but I also don’t have time to provide free consulting. Please let me know if you have any questions or concerns about contacting me at [email protected].

 

Sending Comments and Asking Questions

Anyone who reads my blog for very long understands that supporting my books is a big deal for me. I actively work with my readers because I realize that you have the choice of using books written by other authors. Let’s just say that my support system is one of the reasons you really do want to buy my books. My blog not only answers common questions you have, but also adds examples and other information to the information you already receive through my books, so make sure you keep you eyes peeled for additional information here as well.

The last time I discussed this topic was in 2011 in my Contact Me, Please! post. The same things apply now as they did then. I’ll answer your book-specific questions as soon as I possibly can and in as much detail as I can. However, I won’t write your school term paper for you, accept a marriage proposal, or provide free consulting (amongst other things readers have asked me to do in the past). If you’re having problems with an example or can’t find the book’s source code, please be sure to ask because I want your experience with my books to be nothing less than phenomenal.

I also encourage you to be a beta reader. You can see the posts I’ve made for several recent books. The biggest reason for me to ask readers to participate in the book building process is to ensure you get the book you want. I also want to avoid Errors in Writing. As far as I know, I’m the only technical author on the planet that invites reader comment during the writing process, but I truly feel your input is essential, so I request it in every way I can. As I get new book contracts, you’ll continue to see requests for beta readers posted on my blog.

You can always contact me at [email protected] with any comments and questions you have. This includes both books and blog posts. Let me know about any concerns you might have and I’ll do my best to solve them. In the meantime, happy reading !