Code Complete: A Practical Handbook of Software Construction

Widely considered one of the best practical guides to programming, Steve McConnell ’s original “Code Complete” has been helping developers write better software for over three decades. The author’s timeless techniques and strategies are still relevant in spite of the evolution of programming languages or the shift from waterfall to agile. He revises the impact these changes have had on the software environment together with Jeffrey Van Gogh, Director of Software Engineering at Google. They don’t step away from covering some of the controversial subjects from the book and give relevant advice for programmers that are just entering this space.

---

The evolution of programming languages in the last 30 years

Jeffrey Van Gogh: Hi, there. I'm Jeffrey van Gogh, I'm a director of engineering at Google working on programming language support for Android. I've been in the software industry for over 20 years, always working on Developer Tools and other related efforts. Today, I have the pleasure to interview Steve McConnell, who is the author of the "Code Complete" book that came out 30 years ago. Welcome, Steve McConnell.

Steve McConnell: Jeffrey, thanks for that nice welcome. And at the risk of doubling down on how long my book has been out, the second edition came out only 19 years ago. So, a little bit more recent.

Jeffrey Van Gogh: Cool. Oh, that's a pretty good lead into my first question. So, the first edition of your book indeed came out 30 years ago and in that, you use a lot of examples in Pascal, Basic, and Fortran. And then your second edition, you switch to using Java and C++ and C#. And of course, since then, in the last 19 years, programming languages have been different further. What's your thought on this evolution? What's the biggest changes you see?

Steve McConnell: Well, clearly, there's been a significant amount of language evolution, especially since the first edition of the book came out and I think also since the second edition of the book came out. I guess it's kind of interesting to me that, I think when the first edition of the book came out, there were 11 years before the second came out. And by that time, I think the languages that I used, especially just GW-Basic, Fortran, and so on, were very much out of usage at that point. The languages from the second edition, I think, have been much longer lived, Java, C#, even Visual Basic. And I think there continued to be evolutions in the language design. And really, I kind of throw that back to you. I mean, you've been so involved in the development of Kotlin and I believe you're the secretary of the Kotlin Foundation. So, you know, what do you think about recent development in languages?

Jeffrey Van Gogh: At first, I worked a lot with both C# and Kotlin over the years. I think what I've seen is that we have everything going to cloud and much more client and server side, asynchronous has become a lot more important. And so, you've naturally seen languages evolve around that, right? Kotlin has coroutine supports, it makes it much easier to do asynchronous programming without having to do a lot of callbacks and state machines. So, I think you definitely see that language has tried to keep up with developments in the larger industry.

Recommended talk: Simplicity & Complexity: The Beauty & the Beast? • Sander Hoogendoorn & Kevlin Henney • GOTO 2022

Steve McConnell: Yeah, the asynchronous part is interesting. Right after "Code Complete," the first edition came out, I went to work on a project and there was a companion project. So, bear in mind, this is 30 years ago, and one of the requirements they had was they had to support asynchronous processing. And I think that one requirement 30 years ago easily doubled or tripled the amount of effort on the whole project. So, what you're saying, it sounds like, is that now that would not be the case?

Jeffrey Van Gogh: Yes, hopefully. I mean, you still have to think about it a lot, right? Like, things can go wrong, like, your network requests can fail. So, definitely still extra mental things you have to consider but these languages are trying to make it easier.

Steve McConnell: Yes.

From waterfall to agile: the impact on code

Jeffrey Van Gogh: When the book came out, other thing that's, I think, different today, like, software was much more likely to be released in a waterfall model, where, these days, agile programming is all the hype, A/B testing, releasing something several times a day. How do you think this has impacted, like, the coding that people do?

Steve McConnell: Well, I think that when the first edition came out, I think coding was more often a write-once activity and I think it was less common for programmers to go back over the code they'd written multiple times over and over again. You know, as you said, with the move to frequent releases, I think it's just way more common for programmers to revise code that they've written pretty recently as well as code that they might have written a while back. To me, that's an excellent feedback loop. I think one of the humbling dynamics that most of us have experienced at some point in our careers is going over a section of code, having it be really hard to figure out, and in our minds thinking, "Geez, what Bozo wrote this?" And then realizing, "Oh, it was me, I wrote it."

And I think having that experience a couple of times is incredibly valuable because it helps to sensitize you to the fact that coding is partly about communicating with the computer, but it's also partly about...I would say mainly about communicating with other human beings. And my view for a long time now has been getting the code to work is just table stakes for getting paid as a programmer. If you can't get the code to work, then why are you even getting paid to do the job? But the difference between somebody who's just getting paid versus someone who's actually taking pride in their work and who's good at what they do, I think a lot of that comes down to, "Are they writing the code so that other humans can understand?"

Should source code be the only documentation?

Jeffrey Van Gogh: That actually ties to the next question I had. You mentioned in the book that source code is the only documentation. How do you think about it now? Like, if people are looking at the code more often and taking pride in it, do you think that is still applicable?

Steve McConnell: I've kind of gotten in trouble for that statement over the years, I think, because it was not my intent ever to say that source code should be the only documentation. But it was my intent to make the observation that, for better or worse, a lot of times, it does end up being the only documentation. The argument I tried to make in the book was, "Look, given the reality that a lot of times that's how it ends up, it makes sense to put effort into the code itself to make it as self-documenting as possible." And it wasn't really my intent ever to say that that's the only thing anyone should ever do. But, you know, as a practical matter, we still see all kinds of code bases with very little external documentation.

And the fact is external documentation tends to get out of date really quickly, it doesn't tend to be maintained. Even internal documentation in the form of comments often gets out of date. And in a sense that being a problem, you know, our psychology on this is kind of interesting where if you read a comment that says one thing and then you look at the code and it's doing a slightly different thing, even though anybody who has been doing this for any length of time knows that the code is probably definitive, in our minds, we tend to look at the comment and then think that the code should match the comment. And so, really, that psychology is backwards.

Probably most of the time, we should look at the code and see if the comment doesn't match, then the comment is probably what's wrong. When I was at Microsoft a million years ago, there was a phrase in vogue that was, "A bug in the comments is a bug in the code." And I think that that's actually a very wise saying because if a programmer comes in and looks at the comment and sees code that doesn't match, there is a chance that the programmer will then modify the code to match the comment and now all of a sudden, it's actually the code that's wrong. So, I don't know what your experience is on that but that's kind of the way that I've seen it.

Jeffrey Van Gogh:One thing that I've seen is that especially at companies like Google, we have incredible tooling to help understand the code better, right? Like, we have like code shirts and kites to, like, look at code at scale and be able to jump the definitions and references at a monorepo of millions and millions of lines of code. That definitely helps. So, maybe just throwing the question back to you, do you think that the enhancements in IDE has make this easier? Or do you think people need to do better at documentation still?

Recommended talk: Getting to Know IntelliJ IDEA • Trisha Gee & Helen Scott • GOTO 2023

Steve McConnell: Oh, yeah, absolutely. In the first edition of the book, I had a section on my vision for what would be the ideal programming environment, essentially the ideal IDE. And even by the time the second edition came out 19 years ago, I had taken out that description because even 19 years ago, it largely existed. I think tooling makes a huge difference even in just the ability to comprehend. You know, I've joked that I probably wouldn't have been able to write "Code Complete" without Words Outline mode. And the reason is because, in the Outline mode, I can very easily jump to any level of detail I need to, I can go out to the 30,000-foot view, I can go to the 10,000-foot view, I can go to the 500-foot view, and then I can go on to the ground.

I can do all that very rapidly back and forth as much as I need to, and that ability to understand the big picture and the details, I think, is something that is really important in anything that has to have any conceptual integrity. I don't see a huge difference there between that activity in writing a large book versus that activity in working on a large program. So, to the degree, that similar kinds of tools exist, you know, the jump to depth, etc., it reduces the mental load on your brain. You can focus on the stuff that really matters instead of spending most of your brain cycles searching, which is not really a super good use of brainpower.

Jeffrey Van Gogh: Makes sense. Of course, no matter how complex the tooling gets, like, it doesn't matter if your code is sloppy, like, it's still hard to read. Right? And I was watching this video recently from 1975 that was posted on YouTube about critical program reading. I thought it was interesting that this is still a highly debated topic, right? Like, here at Google, people are still teaching folks how to make sure that they don't have complex branches that are, like, nested six levels deep. What are your thoughts on that whole area?

Steve McConnell: Well, I have lots and lots of thoughts on that area. I do think I've seen that video as well, thank you for sharing it. I think that video was ahead of its time in 1975. Early in my career, I worked on a project that was required to be implemented in Fortran 77 or 77 was a reference to the year that the standard was adopted. This was quite a few years after 1977, I'm not that old. But one of the limitations of Fortran 77 was that it was six-character variable names and everything was in all caps.

And so, when that video came out in 1975, they were talking about how you should make everything super readable. There's only so much you can do when your technology only gives you six characters to name your variable. So, it's easy to agree with the advice in that video now, but I think it would have been largely impossible to implement that advice when the video came out. So, it's a really interesting video to watch if you have a knowledge of how things have evolved over the years.

Jeffrey Van Gogh: Makes sense. And so, I was recently helping to judge a student contest for the Kotlin Foundation. And similar to what you mentioned about, like, source code commenting and so on, I realized that this is not a skill that is taught a lot at universities, right? Like, writing readable and maintainable code. What do you think we can do there to make that better?

Steve McConnell: Yeah, I think...well, universities, I think, are largely focused on teaching people how to program and just how to get the program to work. As I said a few minutes ago, that's kind of table stakes just for being able to get paid for this but it's not really the whole profession. And when you bring up examples like code that's nested six levels deep, again, I think that, to me, kind of falls into the category of puzzle solving. And I think this is a bit of an occupational hazard for programmers because a lot of us got into this activity in the first place because we liked the puzzle-solving aspect of it. I still like the puzzle-solving aspect of it.

So, if I'm writing code purely for my own use and all I care about is solving the puzzle, fine, I can do whatever I want.I can challenge myself, "Hey, I'm going to try to understand this eighth-level deep nesting." I probably can't do that. Probably very few human beings can. But if I'm going to work in an environment where other people have to understand what I'm working on, then, yeah, that's...I mean, that might be okay for the puzzle-solving activity, it's not okay for the commercial production code activity, where I'm going to rework the code at some point, somebody else is going to rework the code maybe while I'm still available to consult on it. And then who knows? Time goes by.

I think one thing we've learned over the years is that code lasts a lot longer than people think it's going to. Especially if a system is successful, there's typically code buried down in the deep depths of successful systems that's been there from the beginning. And if that wasn't written for sake of clarity, you know, then it's going to be a real challenge. One of the early assignments I got, I've been working...I think I've been working for about five years at this point, but I got a consulting assignment to go in and try to revise some of the core code in a relational database manager.

The core code had originally been written in Fortran, and then it had gone through an automated conversion program to convert it to C. And so, my job was basically to go in and try to optimize this code that had been machine converted from Fortran to C. Fortran is not that readable in the first place and neither is C. And when you try to merge the two, it's just a disaster. So, from a puzzle-solving point of view, it was kind of an interesting intellectual exercise. But they actually had to hire somebody specifically to come in and look at it because nobody who actually worked for the company was willing to do it and I think that's what you get into when people don't pay enough attention to trying to make the code readable for other humans.

Full-stack vs a single programming language

Jeffrey Van Gogh: Make sense. Cool. In your book, you talk about sticking to one programming language at a time. Do you think that still applies today, especially as we're looking at full-stack development where people are building both the server side and the client sites?

Steve McConnell: You asked at the beginning about what's changed in coding and I think that's a big thing that's changed in coding. I think in the first edition of "Code Complete," there were a lot of programmers who had essentially only ever learned one programming language. And if they learned a second programming language, it was in the transition from university to their job or maybe after they'd been at their first job a few years. But it wasn't something people went back and forth on routinely with any...at least not commonly. By the time the second edition came out, I think it was a lot more common for people to have had experience in multiple languages. But, you know, wow, in the last 20 years, I think it's just so common for people to be working on front-end stuff, back-end stuff, scripting stuff, or traditional language stuff. I think it's just...I think it would be pretty hard to be a programmer these days and not get exposure to multiple languages. At least that's my perspective. So, what's your perspective on that?

Jeffrey Van Gogh: Well, yeah, I mean, I've probably a very specific perspective on that. As I mentioned, I work on Developer Tools, specifically programming languages and compilers, right? And so, when I hire people to join my team to work on the compiler, I'm looking for people who have that skills on the compilers, not necessarily on that language. And people who like compilers and like program languages, they can probably learn the language in a couple of weeks, right? Like, they will open the formal language spec and it's like, "Oh, let me see how I can break this language," and learn it that way. And actually, that's what I often ask in my interview questions for those folks. I was like, "Hey, what's your favorite programming language?" And usually, people have a favorite. And then my next question is, "What feature do you dislike most and how would you redesign it?" And if you really like a language, there's always some words in the language that, like, you would like that it was redesigned, right?

Steve McConnell: Okay, so what's your favorite feature of Kotlin?

Recommended talk: Functional Programming with Kotlin • Hadi Hariri • GOTO 2018

Jeffrey Van Gogh: I mean, absolutely, coroutine is a great feature to make asynchronous programming easier. I think that's pretty obvious, people like it. One feature that might be a bit more kinesthetic, the ability to have a receiver on lambda functions makes it much easier to build the patterns. And I'm guessing your next question is, which feature do I dislike the most?

Steve McConnell: I don't know if I want to put you on the spot but if you think you can answer that, go ahead.

Jeffrey Van Gogh: No, I think I've been on record saying this. I think the lateinit variables are...I mean, it's unfortunately needed to deal with some interrupted existing Java code. But it really kind of breaks the type system because now, like, Kotlin is supposed to be null safe, and then with lateinit, it's like, "Well, you can initialize this later but if you...like, if your state machine and your cloud is not correct, then you can still get NullPointerExceptions." So, it's like this feature breaking the type system.

Steve McConnell: So on the topic of programmers learning more than one language, I think there are lots of languages that are all pretty similar. I mean, a lot of the procedural languages are pretty similar. If you learn one, there's not much involved in learning another one. If there's some deltas in terms of syntax, in some cases, the deltas can be incredibly minor. And so, I kind of think that these days, the idea of...in both editions of the book, I make the comment that learning a second programming language really well tends to be a watershed event in the development of a programmer.

But I'm not really referring to learning a second language that's almost identical to the first. I'm talking about learning something that's significantly different like going from C# to Lisp or something like that, or to a scripting language, I think that would count too. A weakly typed language rather than a strongly typed language. I think for me, that experience happened when I learned APL. I don't even know if that language exists anymore, but APL stood for A Programming Language. It has its own character set. It's not a procedural language in any sense of the imagination. At the time, you had to actually get a different video card that you stuck in your computer and then the box came with stickers that you'd put on the keys of your keyboard on the front edges so that you can keep track of where the Iota function was and that kind of thing. But it was...

Jeffrey Van Gogh: That's quite a commitment to switching to a different programming language.

Steve McConnell: It is. Then the concept was everything you ever did was persistent in the workspace. So, there is this concept of a workspace, and it just kind of everything hanging out there. So, learning that, I think I did see programmers who would try to learn APL coming from, at the time, it would have been Fortran or Basic or Pascal, and they're trying to write Fortran, like they're trying to write a loop in APL. Well, APL, it does loops but that's not the way to do it in APL. They have a much more elegant syntax. I mean, essentially, it would be the equivalent of a for-each statement now, or the ability to assign all the elements of an array to another array with one line of code, that kind of thing.

And it had way more elaborate capabilities in that area because it was mostly a matrix manipulation language. At least that's how I was using it. I think the other thing that's kind of interesting is I know you were showing me some code in Kotlin the other day and I had to...since it's not a language I'm familiar with, I had to ask you whether the result of an if statement was a comment or an executable code. And later, I realized that the reason I asked you that was because of the color coding. I spent a lot of time in Visual Basic. In Visual Basic, green is comments.

And so, my mind when I saw the green code was like, "Huh, that must be a comment." But of course, it's not because it's a different environment, different expectations. So, I think that's just one of the ways that programmers' minds get really finely attuned to patterns, even colors, and I don't know if I could change that so that it was a different color if I was doing that myself. But our brains get attuned to super fine details, including things like the capitalization, whether the initial letter on a variable is capitalized or not, where the braces go. And while a lot of those details are arbitrary, they become imprinted in our brains and we start to expect the pattern to look like that.

Jeffrey Van Gogh: Absolutely. I mean, I programmed in C# for the first half of my career and then switch to Java and Kotlin, and C#, I mean, it has braces on the new line and Pascal casing, and Java and Kotlin, camel casing and brace from the end of the line, right? When I look at C# code now, I'm like, "Whoa, that looks weird," even though I probably didn't write a program in it for over 10 years.

Steve McConnell: Exactly. That's my experience as well is that when you're working in it, it looks normal and other things look weird, and then you shift to something else...I did my undergraduate major thesis on Thomas Kuhn's book, "Structure of Scientific Revolutions," and that's where the term paradigm shift came from. And part of the notion of a paradigm shift is that it's a gestalt change that you can't...the word he used is incommensurate, meaning you can't compare point by point and just do a mapping, that there's a gestalt change that occurs all at once. And I think that is true of understanding programming idioms or formatting conventions, in particular, where...at some point, I've had the experience where my brain just flips over and the new style looks normal and the old style looks weird.

Jeffrey Van Gogh: Makes sense. I mean, talking about, like, formatting conventions, like, I think one of the things I've seen at least changed in my part of the industry is that instead of these endless discussions and even flame wars about, like, how code should be formatted, we're moving much more to just having a tool do it and use whatever the tool does. Do you think that that is useful?

Steve McConnell: You know, I definitely have mixed feelings about that. I think given that programmer comprehension is determined by the specific details of the programming style and it's largely independent of the merit of the details, it's just the details that they're used to, then on the one hand, I think having programmers be able to write in the style that they're used to and then have the environment change it to the group standard, there's value in that. On the other hand, if you ever have to comprehend code somebody else wrote and now, you're trying to comprehend code that's in the group style that you haven't let your brain lock onto yet, you know, that becomes problematic, I think.

I'm not somebody who thinks everybody's brain works exactly the same way, so I'm not...there probably are tons of exceptions to this. But I do think that there's value in making sure that everybody on a team is fluent in reading code that is written in the team style. And if everybody's fluent in reading code that's written in a team style, I'm not sure why it wouldn't be written that way in the first place. But I think as long as people are fluent in reading their code, I don't suppose it really matters that much how it's written as long as it gets converted to that at some point.

Open source and its impact on code’s lifecycle

Jeffrey Van Gogh: Yeah. Another thing that has changed since the book came out is the prevalence of open source. When it came out, I think open source was in its infancy. I think Linux was there. But today, we have this huge ecosystem where for basically any programming language, if you need a library, there's probably a third-party open-source library for it that you can just package-manage into your application, right? Do you think this has a big impact on the software construction lifecycle?

Steve McConnell: I don't know if it does have a big impact but I think it should have a big impact. I think, around the time "Code Complete 1" came out, there were some really good, I think, opinion pieces that had been written on people becoming professional programmers never having seen a life-size program. They had never seen the architecture of a life-size program, they've never seen the code or the coding standards of a life-size program. All they've seen was the code that was part of their university assignments. The commentary was along the lines of can you imagine if someone became an architect going all the way through university education, never having actually seen any life-size buildings, never having studied the detailed plans for those life-size buildings?

The same thing for engineering, can you imagine engineer going...civil engineer going through university and never seeing a real bridge, never studying the design specs for a real bridge, never going through the calculations of the loads and so on on a real bridge? This is all incomprehensible, right? It wouldn't make any sense. But in programming, we had managed to get pretty far into the evolution of the field while the university system never expose students to life-size problems. And so, I think open source has been, at least potentially, enormously useful in support of that.

Universities can bring in large open-source systems and have the students study those so that there aren't any confidentiality issues involved, the students can get exposed to the architectures and the details of really good-sized systems. So, I think that's all possible now. I don't have a good window into how much that actually happens now. I know that you've interviewed lots of candidates over the recent years. So, I mean, what have you seen? Do you feel like people are coming out of university exposed to that kind of thing?

Jeffrey Van Gogh: I think it's mixed. I mean, there's definitely people who have been working on open-source project, like, their whole student time and I think it does show that but I don't think it's like ubiquitous. I do think, like, the software has changed. It's like, "Oh, I need this helper, let me just get this open-source library, it's pretty easy." At the same time, it also creates some more risks. Like, there's so much more focus these days on supply chain security and there's been some documented cases where some open-source libraries were either hacked or the owner was malicious. And that's something you have to consider when you take a dependency on these great open-source libraries, right?

Recommended talk: Security Styles • Eleanor Saitta • GOTO 2022

Steve McConnell: If I was to classify...for the sake of this particular point, classify open-source as a particular kind of reuse, one of the ways that you see errors show up in reuse is when the code is reused for a purpose other than what it was originally intended for. And so, even if you leave aside the idea of maliciousness, if somebody looks at an open source code and says, "Well, this is pretty close to what I want but I'm going to use it in a slightly different way than it was intended to," even if you've had thousands of eyeballs on that open source code, if they weren't on it for the new usage that's now planned, it's possible that there's some error in there that was just never considered because that wasn't how the usage was conceived in the first place.

Jeffrey Van Gogh: True, but that's kind of true for any API that you consume, right? Like, you know, Microsoft was famous for having all these crazy backwards compatibility for apps that use APIs in a way. Google has a Hyrum's law saying that any API design that gets current implementation is the de facto documentation, right?

Steve McConnell: I had experiences with that when I was at Microsoft too. And I agree with the statement that the spec or the requirement is the current behavior, both the intended and unintended current behavior, or however you want to characterize it, designed and redesigned, or, you know, even accidental behavior. You get lots of incidents where if something's popular enough, there's some side effect that was never really intended, and then that has to become part of the standard going forward because so many programmers have relied on that particular side effect. I think you and I both have been involved in similar kinds of discussions in the companies we've worked out where...like when I was at Microsoft a long time ago, there were these books that kind of came out called "Undocumented APIs."

I always was amused by the titles of these books because the way the so-called undocumented APIs worked was you had to access them using Assembly language, you had to manually put arguments on the stack, then you had to use a go-to to begin execution at a particular memory location, and that's not exactly an API the way I think of it. But the effect was that going forward, it created this crazy support obligation where Microsoft had to support...essentially had to support people who've been hacking into their system but in kind of consistent ways. And in some cases, that actually significantly limited how you were able to evolve the design going forward because you had to support this really kind of gnarly way that people have been accessing it, which was never documented in the first place and wasn't even really a legitimate way to get into it.

Jeffrey Van Gogh: That's pretty painful. I guess those books, like, undoes the title itself the moment that it was published because it's a documented API.

Steve McConnell: Right, the instant you publish undocumented APIs, they're documented, so it's a self-invalidating title.

Controversial points from Code Complete over time

Jeffrey Van Gogh: Going back to your book, so what were some of the more controversial standpoints in the book and how have those played out over time?

Steve McConnell: I don't know how much of it was controversial but I think there have been issues that were controversial long before I wrote my book but that I happen to cover in my book, that I'm just kind of shocked are still even a little bit controversial today. So, like, I do have a pet peeve around the use of i, j, and K for indexes, and my pet peeve is really twofold. Well, it's at least twofold. One is it's lazy. Two is the names are subject to overloading, you can end up reusing i in the same routine or the same scope and introducing subtle errors as a result of that. And my biggest objection is just that I think it's a missed documentation opportunity, and we talked earlier about self-documenting code.

You're never looping through i's, you're looping through something, you're looping through images or records or pointers or files or, you know, who knows what, but it's not i's. Whatever it is, it's not i's. And there was actually a LinkedIn discussion within the last month where I think it was probably an older programmer who was saying, "Hey, a few confessions here, I'm still using i in my programming." And there were dozens and dozens of comments, mostly from other people who look like older programmers who are like, "Yeah, i, nothing wrong with i, i works fine." And it's like, yes, it's not that i is incomprehensible, the idiom is incredibly well-established. It's just that there is a better alternative if you focus on the perspective of the reader of the code, not the writer of the code.

And to the reader of the code, if you can insert semantically useful information in the name of the variable, then you should be doing that. I don't care if you've only got one line of code in your for loop, I just think i is still not documenting the code as well as it could be. And you're like, "Well, it's not too hard for people to figure this out." Okay, fine, but I think the aspiration here is people should never...people should have to figure out things in the code as little as possible. Mostly, they should just be able to read it and know what the intent is. And the more you tax people's brains by setting up situations where they have to figure something out, the more likely it is at some point somebody's not going to quite figure it out and they're going to insert an error and then, you know, who knows what the consequence of that error is? In your environment, the consequences could be catastrophic.

Tooling

Jeffrey Van Gogh: Oh, yes, billions and billions of users and devices, so, obviously, make sure correctness is key. So, during the COVID pandemic, both you and I worked on some personal coding projects, and I couldn't help notice that, like, where I was using Source Control, CI/CD, adding tests, you were using Excel, VBA, and WordPress, and I couldn't help but think about the cobbler's children. Can you comment on that?

Steve McConnell: I think in a way, you kind of set up a false contrast by saying that you were using Source Code Control, CI/CD, and adding tests. I had all those things, they just weren't structured in a way that you would normally think that they were those things. So, the Excel code was all on OneDrive, which was a version back to the beginning. I don't know that there's really any integration or deployment to be considered in that scenario because everything's kind of always integrate. I guess you could characterize it as a monolithic stack if you want to call it that. And then just the nature of what I was doing was that essentially, the whole codebase got exercised all the time.

But I will say that, compared to what would have been possible 20 or 30 years ago, the ability to just write some code and immediately execute it and see what happens is just so much vastly better now than it was. The ability to move quickly in that environment, I think, is good. You're not the only person who's given me a hard time about having an affinity for VBA but one of the things that I really like is I like solving problems with the minimal amount of work or the minimal amount of design and tools that is needed to solve the problem.

For what I was trying to do, which was to do some data analysis, to constantly be evolving how I was doing data analysis and then very significantly have lots and lots of outputs in graphical format where I put a lot of emphasis into iterating on the graph formats and so on, essentially, I was using Excel as the front end for prototyping calculations and as the back end for the graph displays. And I think you missed part of my stack, which is that my technical stack was VBA, Excel, OneDrive, WordPress, and some WordPress plugins. And on the one hand, it's a very Rube Goldberg stack and I doubt very many professional programmers would take pride in that or even call it a stack.

But on the other hand, for my purposes, which was as a hobby activity, trying to spit out about 500 graphs a day with one press of a button and get those all updated on the website, the stack that I had set up allowed me to hit one button in Excel, run a bunch of VBA code, generate graphs and PDFs, put out 500-ish of those to OneDrive and have those all updated automatically on the website. So, my objective there was minimizing the amount of effort I had to spend to publish that stuff and keep it updated and really without having to learn any huge new stack all the way as part of the process and it worked fine for that.

There definitely were some limitations that I ran into by the end of it, which you and I have talked about, like I couldn't create interactive graphs on the web with that stack, which would have been nice and that wasn't a possibility. But I think to me, I think it's kind of like...I go back to the designing tools idea, and one way that I've thought about designing tools is what allows you to expose the maximum amount of surface area with the minimum amount of work. And I think that initiative, I was able to expose an awful lot of surface area without all that much work, so I'm still pretty satisfied with that as my solution.

Jeffrey Van Gogh: And if I remember correctly, your model for the COVID data was one of the more precise ones anyway, right?

Steve McConnell: Yes, there's a paper in the "Proceedings of the National Academy of Sciences" that rated my forecasting model as the fourth most accurate model overall, it was more accurate than the models from MIT. Harvard, Google, sorry, Walmart, London School of Hygiene and Tropical Medicine, Johns Hopkins. Yeah, so there were only three other models that were more accurate than mine.

Jeffrey Van Gogh: Excel is redeemed.

Steve McConnell: Yes, exactly. So what about your pandemic project?

Jeffrey Van Gogh: We both were helping nonprofits organize virtual fundraisers. And so, I program this project to control OBS and do teleprompting for these virtual events. So, I could control the whole virtual event, which is the tablet, going from scene to scene, starting videos, giving the people on camera teleprompting cues. I had a bit more elaborate deck, I had an OGS web server written in TypeScript and then an Android app on a tablet written in Kotlin. So a bit more elaborate because it has a server component interacting with client-server, I needed a CI/CD system with testing, etc., so the requirements were very different, obviously.

Should tech lead managers code?

Steve McConnell: Well, I think an interesting aspect of that is you and I are both doing programming as a hobby, essentially, or as a leisure activity anyway. And in my case, I no longer do programming as part of my day-to-day work but I still enjoy the mental exercise and I really enjoyed being able to spend a little bit more time on that throughout the pandemic. And I don't know, your work is...your day job is extremely technical but...

Jeffrey Van Gogh: It is, a little. I don't get to do a lot of coding these days anymore, right?

Steve McConnell: Yes..

Jeffrey Van Gogh: Yes, and maybe it's a good segue into my next question. In your book, you exclude management from being part of software construction. And especially these days where like...and the news recently was that Meta Facebook is pushing managers once again to have technical contributions. What are your thoughts on, like, managers who code or not code?

Steve McConnell: I'm not familiar with all the details of what Meta is requiring, so I don't know, does technical contribution mean actually contributing production code?

Jeffrey Van Gogh: That's a good question. I don't want the detail. I know at Google, engineering managers are expected to still be technical, even though that doesn't mean coding. For me, I'm participating in the Kotlin Language Committee where we review breaking changes to the language and we go deep into the type system. I consider it highly technical, even though I'm not writing product code, right?

Steve McConnell: I definitely know that there are organizations that expect at least first-level managers to be contributing production code and for a long time, Microsoft was one of them. In my day job, which for the last 25 years has been the CEO of Construx Software, which is we do consulting and training in the software industry. So, we get to work with anywhere from dozens to hundreds of companies in any given year, and over the years, I've certainly worked with hundreds, cumulatively. And I would say I don't really know how well that idea ever worked at Microsoft. I think it basically was just part of contributing to what for a long time was a pressure cooker environment with really long hours at Microsoft, which I think is still true in places at Microsoft but maybe not as universally true as it was when I was there.

Then I see other companies that are not Microsoft and they can't hire the same kinds of people that Meta or Microsoft or Google can hire, who are looking at these other companies and saying, "Yeah, we want our managers to code too because managers at Meta are programming or managers at Google are programming." And so, they asked me, "You know, is this a good idea? Is this going to work for us?" And my first response is, "Well, do you think that you're hiring as selectively as Google is or Meta is? Or, you know, are you getting 100 resumes for every open position or 1,000 resumes for every open position?" And if the answer to that question is not yes, then I'd say you're just not hiring from the same part of the talent pool, you can't have the same expectations.

It's unclear to me whether it's a good idea even at the places where they're hiring from the top, less than 1% of the talent pool. But getting below the top 1%, I think it becomes just increasingly unrealistic. I think you want your managers to be good at their jobs, whatever their jobs are. And for people who come from a technical background, most organizations...I don't know that this is the greatest idea but most organizations tend to promote their better technical people or best technical people into human management positions. And we've joked literally for decades that a lot of organizations hurt themselves in two different ways. They deprive themselves of really valuable technical resources and they give themselves an untrained people manager who's just not really ready.

And so, given that a lot of the people managers in technical organizations are coming from the technical ranks, the ground that needs to be made up there is not becoming more technical, the ground that needs to be made up there is the soft skill stuff of how to work with people of different personalities, how to work through conflict, how to communicate under stress, how to listen and how to notice when people have something going on that they're not willing to tell you but be able to perceive that they've got an issue. I mean, these are the growth areas that most new technical managers need. And I think a focus on continuing to write production code normally most of the time undermines the development that the new managers need to be doing. So, that'd be my perspective.

Are there exceptions? of course, there always are exceptions but I think in the main...that's not the development that we're really looking for from our technical managers. I go through an exercise in a leadership class that I teach where I asked people to interview each other about the best team they've ever been on and I asked them to list, "What was the contribution of the manager to the best team that you've ever been on?" And I've had hundreds of people go through this exercise, I don't think I have ever...out of hundreds of people, ever had anyone say that the way their manager contributed to the best team they'd ever been on was through technical expertise or through being the referee on technical questions. It's always soft skill stuff, it's always trusted us, empowered us, listen to us, helped us gel as a team, was really good at addressing conflict in constructive ways, and that kind of thing.

Jeffrey Van Gogh: Makes sense. Thanks.

Steve McConnell: So, I gave a long answer on that as I've been doing throughout this conversation. But, you know, in your experience, what have you seen? Not just with yourself, I think you have quite a number of managers under you as well, what do you see in that area?

Jeffrey Van Gogh: So, I do agree that writing production code is probably not a good idea, right? Managers get dragged into meetings all the time, we have to do performance reviews, we have to do planning. If you're still writing production code, you actually put the schedule of your project at risk, right?

Steve McConnell: Yes.

Jeffrey Van Gogh: At the same time, I do think it's good to remain technical so that you can mentor the people who are reporting to you but that can be done in different ways, right? Like, as I mentioned, I do the Kotlin Language Committee, I do write some analysis of our metrics data and see if I can find patterns. But those I can delay, right? If I don't get these nice new metrics up and running, well, then we don't have nice new metrics but we're not putting the project at risk because the schedule slips.

Steve McConnell: So, what do you think about kind of the social dynamics or the political dynamics of having the manager contributing code? Is the manager able to contribute code as an equal and be reviewed and critiqued as an equal?

Recommended talk: What Engineering Managers Should Do (and Why We Don’t) • Lena Reinhard • GOTO 2019

Jeffrey Van Gogh: I think you need to be open. I mean, if you think that you're above the team, it's a bad idea, right? And I've seen some mistakes at other companies, I won't name names, but I have a case where a senior manager went through the code in the holiday break and rewrote a whole bunch of code because he thought it wasn't at the standard that he wanted. That pissed off that team immensely when they came back from vacation, right? So you have to be super careful, like, you can contribute but you need to be humble about it.

Steve McConnell: I'd be curious about...on that example you mentioned, I would speculate that even if that manager didn't introduce any errors in the activity, it's still essentially undermining a team's sense of ownership of its code. And I've seen both, I've seen those cases where, in a way, there's no harm done technically but there's a lot of harm done to morale. But I've also seen the case where there's harm done technically where they insert all kinds of errors because they're not in the day-to-day discussion, they don't understand all of the detail and considerations and...

Jeffrey Van Gogh: Like, "Why is this code so complex? Let me just make it simpler," and, like, not realizing there's like all these background things and risks and stuff.

Steve McConnell: One of the worst examples I've seen of that is in a company that had grown into about 200 staff but the CEO really...the CEO is the founder and he really liked coding and occasionally he would come in on the weekend and write a bunch of code and check it in and change other people's code. And then you're not only having to work with your manager doing it, you're having to work with the owner of the company doing it, it was very destructive.

Jeffrey Van Gogh: So it's interesting to see what happens and I think we have to be careful as managers to what kind of coding we still do and see if we can have other ways to be technically involved, right?

Steve McConnell: Yes.

Research for writing the book

Jeffrey Van Gogh: As I was reading your book for this interview, I couldn't notice how many references the book had to other literature, like, way more than I've seen in other technical books and almost like a research paper, which is impressive because your book is over 900 pages and it's just sprinkled with amazing references throughout. How much research did you do for writing this book?

Steve McConnell: It was an enormous amount of research. I spent about two years doing background research before I started writing. The origin of the book was I originally thought I would write an article and I thought I wanted to write an article on essentially good programming style and so I went looking for what had already been written. And at the time, I assumed there had to be something out there on the details and ins and outs of what would make for a good software construction. So, my first kind of tranche of research...and this is pre-internet, so my first tranche of research was at the University of Washington research library. And I came away with about 80 articles and a bunch of references to books and it took me quite a while, like, maybe a year to get through reading those articles. I had to request the books because a lot of them weren't readily available.

So, I got through all those and that essentially was the research backbone for the book. By the time I got through all those, I convinced myself that there wasn't actually any book out there or articles out there on this topic and I was just kind of shocked. It seemed like there were books on project management, requirements, design, but there was no book on the main activity that programmers do, writing the code. And so, at that point, I started thinking, "You know, okay, maybe I could write this." So, I just continued looking up articles and requesting more books and reading either all of them or the relevant sections from those. And by the time the first edition came out, I cited about 300 articles and books that were cited specifically somewhere in the book, but I had read another 300-ish for background that I didn't end up citing. So, I read a total of about 600 articles and books in the writing of "Code Complete."

And then for my next book after that, "Rapid Development," I read about another 300 articles and books for that book. So, that was in 1995, basically. And at that time, I felt at that point that I had read every significant book and article that had been published in the field. And I think in 1995, that was probably about the last time it would have been possible for an individual to do that. And that was kind of the beginning of just the massive explosion of available information, not just on the internet, but in terms of published books and articles, there's no way anybody could do that with the amount that's out there today but I think in 1995, it was possible and I think I had done that.

So, when I went to write my third book, "Software Project Survival Guide," one of the rules I imposed on myself was, "You are not allowed to read anything new in writing this book, you've got to be able to write at least one more book without reading a whole lot more stuff." I mostly succeeded in that task of limiting myself to not reading anything else. I think a lot of people who read "Code Complete" view it as something that was written by an expert programmer who happened to have done a lot of research. That's really never how I viewed the book. I viewed the book as more of a research project that was validated by the fact that I had done a lot of production programming. There is some academic research where anybody who has any experience in a commercial setting is just going to call BS on the research. It's like, "I don't really care what your study said, this is dumb, this is not going to work."

So, essentially, I felt like I was serving the role of filter on the research where there was some stuff out there that just… I couldn't match it to my experience in any way, shape, or form, so that stuff didn't make the cut. There's other things where you do get some pretty good answers. It's not to say that all the research is 100% reliable in every context but, you know, you start looking at things like, "Well, what is the cognitive load of having too many levels of nesting?" Well, that's a pretty well-researched topic, you know, and there's explanations for it, like, people's brains that are working short-term memory just can't hold that many temporary items without dropping some.

The same thing for programs that have cryptic variable names including i, j, and k, it basically causes your brain to overload because you're trying to hold too many items in short-term working memory, and most people get a mental Stack Overflow as they're trying to do that. So in that sense, I thought the research was super useful. At the time the first edition came out, what I said was that I felt like I'd learn as much the year I spent writing "Code Complete" as I had learned in any three years that I spent actually programming but I don't think it would have been possible to learn that without actually having spent a bunch of time programming before that.

Jeffrey Van Gogh: Makes sense. And then did you apply the best practices from software construction to writing the book itself as well?

Steve McConnell: I'm a huge fan of peer review and that kind of collaboration. And my experience in writing "Code Complete" was a big part of what made me such a huge fan of that. I think prior to that, I'd actually been more of a lone-wolf contributor. But as I was working on the sample chapters that I was going to submit as part of my proposal to the publisher, I had a handful of friends review the draft chapters that I put together and the comments were just incredibly valuable.I think that the proposal I submitted to the publisher was at least twice as good as it would have been if I hadn't gotten their review comments. It was so valuable that I continued with that kind of peer review throughout the development of the book and I think the book that came out was at least twice as good as the proposal was, in large part because of the contributions of the peer reviews that I got.

I think my self-assessment and my strength as a writer is, I think, that I'm really good at incorporating feedback and criticism. And when I was working on "Code Complete 2," "Code Complete 1" was a manual process, we were sending out paper copies of the chapters and I was getting UPS deliveries of review chapters with handwritten comments for the most part. So, it kind of came in gradually. "Code Complete 2," I distributed the review chapters via PDF and I basically just posted them on a reviewer website. And because I was on kind of an aggressive schedule for "Code Complete 2," I decided that what I was going to do was just save up the review comments and then go through all the comments for one chapter at a time, chapter by chapter.

The experience of that was just brutal because I would get to a chapter and then I had dozens and dozens of reviewers for "Code Complete 2" and after going through like four or five dozen very critical emails all at once on a chapter, it just really was very hard on the ego. So, that was an exercise where I just had to pick myself up and say, "Okay, you know, it's important for the book that I actually read through all this stuff." And most people are actually trying pretty hard to be nice but, you know, a lot of times, technical people just give it to you straight with no sugarcoating. And one person at a time, that's maybe not that hard put up with, but when you're doing like 30 to 50 people at a time, it adds up. So, I haven't repeated that approach on any later book just because my ego couldn't stand that much all at once. But going through...

Jeffrey Van Gogh: I guess this applies to code review request, don't ask for a code review request from 50 people at once.

Steve McConnell: Iff you do get their request, don't read their comments all at once. You know, read a couple of people's and give yourself time to think about it and then read the next person's, you know? And that goes back to the delta comment. If you read five review comments first and then you kind of figure out what you're going to do based on that, then after that...or maybe it's 5 to 10 at first, after that, it's all deltas, most of it is stuff you've seen before so you can kind of skip over it, it doesn't have quite the same emotional effect that slogging through it all at one time does.

Jeffrey Van Gogh: Make sense.

Advice for young programmers

Jeffrey Van Gogh: For folks who are entering the industry today, other than reading your book, what advice would you give them?

Steve McConnell: You know, it's funny that you frame the question that way because I don't...my book is used a lot in university settings, but I never imagined that it would be. My target audience for the book was me five years into my career. And it was basically like, "Okay, the first..." Maybe it was me two years into my career because the first year, I wouldn't have been ready for a lot of the stuff in there, a lot of it would seem like overkill, like, "Why do I have to put this much time into coding standard? Why do I have to think this hard about the design?"

And even in the first year of my career, I don't think I would have been ready to see the value in that. So, I was super clear in my mind that one of the target audiences for the book was me about two years into my career because by then two or three years into my career, I would have been ready for the advice. It does get used a lot in university settings. I guess maybe people have more...well, as a certainty, people have a lot more coding experience now when they get to university than they did when I got to university. So, you know, what advice do I have? I just think getting exposed to actually writing as much code and doing as much design as possible.

And that's probably partly the way that I work, and so I'm really kind of recommending that other people do what would work for me. But I think for me, studying about something doesn't teach me as much as actually doing it and learning from either doing it right or doing it wrong. And so, for me, I had my day job the first several years of my career but I always had some kind of a background startup going on at the time, which was also requiring me to write a lot of code in my free time. And I think, for me, just the practice of that and, you know, I think quantity has a quality all of its own.

And if you're in a production environment, especially if you go into a large company and you're assigned to work on some huge established system and you have to be super cautious about what kind of changes you make, you're just not going to accumulate the quantity, I think, that supports really good learning. So, having something where you can actually do a lot of quantity, I think, that would be part of it. And another part of it I think is...we talked about open source, is read, read as much code as you can. But I want to reflect that back to you, what would you...what advice would you give to somebody newly entering the workforce?

Jeffrey Van Gogh: So, I actually was one of the people who did have to read your book during university, I had a...

Steve McConnell: Oh, sorry.

Jeffrey Van Gogh: No, it was great. We had a software project course, I think it was 1998 back in my second year of college, and so your book was the material for that course. We had done a year of programming at the time, of course, I had done programming since I was six years old but definitely not as methodical as like a professional project. I mean, I think it was definitely helpful to learn more of the processes and making sure that we, like, share code easier and make it understandable. So, it was definitely helpful. I said 1998, that's quite a while ago too, right?

I think today it is very different. Even today, I am doing side projects at home, like some home automation stuff and like the project that we mentioned during COVID. I think it is important to do some coding on your own and learn. Reading, I agree is important. Throughout my career, I've read so many different code bases at varying quality and you learn a lot from reading other people's code. I can definitely agree with that advice.

Steve McConnell: I'd like to circle back for a minute and just talk about what people are ready for at different times. When I was writing my second book, "Rapid Development," which is aimed more at technical leads and managers, I'd always planned to have some kind of extended case study in the book but I couldn't quite figure out how to do it. And so, the first, like, 10 sample chapters, I didn't include anything having to do with anything like a case study. And eventually, I decided, "Okay, I'm just going to do before and after case studies in a lot of the sample chapters where the before case study is what happens if you're not using the good practices and the after case studies are the examples of how things can go well if you are using these practices," whatever is discussed in the chapter.

So, when I sent out the packet of chapters that...or the first set of chapters for review that actually had the case studies in them, the feedback just changed dramatically. All of a sudden, people were very enthusiastic and people were telling me things like, "You haven't seemed that interested in the content up till now but this just seems very different, you seem like you're a lot more interested in this content than you have been up till now." That wasn't true but what was true was that I'd added these case studies. And then I got specific feedback back after the book came out from people in the industry who would say, "When I read these before case studies, the ones where everything's going badly, I feel like you must have been sitting in in our conference room or hearing our discussions because, you know, it just seems like that's exactly what we experience."

I got those comments over and over, and occasionally I get a comment along the lines of, "But the after case studies seem kind of unrealistic, they seem idealized, and does anything ever really work that well?" So, I've gotten that feedback but then I started getting feedback from university professors who were trying to use the book in like a third or fourth-year project management class. And the feedback I got from them was that their students really liked the book as a text, they thought it was well written, and they liked the after case studies, but for the students, the before case studies caused the book to lose credibility because they couldn't believe that people in real settings could ever act so irrationally.

I just thought that's so funny that people in the field think I'm sitting in their conference room listening to their discussions but university students without a lot of real-world experience just can't imagine that the real world would ever work so sloppily and yet, I think we all have seen cases where it does. Every once in a while, I'll have a practicing person in a class who will share that point of view and say, "No, I've never seen anything like you described in the before case studies," and I always think, "I want to work at your company because if you've never seen anything that bad, that's a sign of a really good company."

Jeffrey Van Gogh: Thinking about the thing you mentioned about the students, the thing I can recommend for the students for sure is do an internship, right?

Steve McConnell: Definitely.

Jeffrey Van Gogh: Take some time and learn how the industry really works and you can get a lot of experience in a couple of months.

Steve McConnell: Yes

Jeffrey Van Gogh: Well, thanks so much for chatting today, and congrats on the 30th anniversary of your book.

Steve McConnell: All right. Thank you, Jeffrey Van Gogh. It's been a pleasure.

Jeffrey Van Gogh: Likewise.