Читать книгу Beginning Software Engineering - Stephens Rod - Страница 30

Something that most nonprogrammers (and quite a few programmers) don’t understand is that code is written for people, not for the computer. In fact, the computer doesn’t execute the source code. The code must be compiled, interpreted, and otherwise translated into a sequence of 0s and 1s that the computer can understand.

The computer also doesn’t care what the code does. If you tell it to erase its hard disk (something I don’t recommend), the computer will merrily try to do just that.

The reason I say source code is written for people is that it’s people who must write, understand, and debug the code. The single most important requirement for a program’s code is that it be understandable to the people who write and maintain it.

Now I know I’m going to get a lot of argument over that statement. Programmers have all sorts of favorite goals like optimizing speed, minimizing bugs, and including witty puns in the comments. Those are all important, but if you can’t understand the code, you can’t safely modify it and fix it when it breaks.

Without good documentation, including both design documents and comments inside the code, the poor fool assigned to fix your code will stand little or no chance. This is even more important when you realize that the poor fool may be you. The code you find so obvious and clever today may make no sense at all to you in a year or even a few months. (In some cases, it may not make sense a few hours later.) You owe it to posterity to ensure that your genius is properly understood throughout the ages.

To that end, you need to write code documentation. You don’t need to write enormous tomes explaining that the statement numInvoicesLost = numInvoicesLost + 1 means you are adding 1 to the value numInvoicesLost. You can probably figure that out even if you’ve never seen a line of code before. However, you do need to give yourself and others a trail of breadcrumbs to follow on their quest to figure out why invoices are being sent to employees instead of customers.

Code documentation should include high- and low-level design documents that you can store in the document repository with other kinds of documentation. These provide an overview of the methods the code is using to do whatever it’s supposed to do.

Code documentation should also include comments in the code to help you understand what the code is actually doing and how it works. You don’t need to comment every line of code (see the numInvoicesLost example again), but it should provide a fairly detailed explanation that even the summer intern who was hired only because he’s the boss’s nephew can understand. Debugging code should be an exercise in understanding the code and figuring out why it isn’t doing what it’s supposed to do. It shouldn’t be an IQ test.

JBGE

There’s a school of thought in software engineering that says you should provide code documentation and comments that are “just barely good enough” (JBGE). The idea is that if you provide too much documentation, you end up wasting a lot of time updating it as you make changes to the code.

This philosophy can reduce the amount of documentation you produce, but it’s an idea that’s easy to take too far. Most programmers like to program (that’s why they’re not lawyers or doctors) and writing and updating documentation and comments doesn’t feel like writing code, so sometimes they skip it entirely.

A software engineering joke says, “Real programmers don’t comment their code. If it was hard to write, it should be hard to understand and harder to modify.” Unfortunately I’ve seen plenty of code that proves the connection between poor documentation and difficult modification.

I worked on one project that included more than 55,000 lines of code and fewer than 300 comments. (I wrote a program to count them.) And if there were design documents, I never heard about them. I’m sure the code made sense when it was written, but modifying it was next to impossible. I sometimes spent 4 or 5 days studying the code, trying to figure out how it worked before changing one or two lines. Even after all that time, there was a decent chance I misunderstood something and the change added a new bug. Then I got to remove the change and start over.

I worked on another project that included tons of comments. Probably more than 80 percent of the lines of code included a comment. They were easy to ignore most of the time, but they were always there if you needed them.

After we transferred the project to the company’s maintenance organization, the folks in the organization went on a JBGE bender and removed every comment that they felt wasn’t absolutely necessary to understand the code. A few months later, they admitted that they couldn’t maintain the code because – …drumroll… – they couldn’t understand it. In the end, they put all the comments back and just ignored them when they didn’t need them.

Yes, excessive code documentation and comments are a hassle and slow you down, so you can’t rush off to the next task, but suck it up and write it down while it’s still fresh in your mind. You don’t need to constantly update your comments every time you change a line of code. Wait until you finish writing and testing a chunk of code. Then write it up and move on with a clear conscience. Comments may slow you down a bit, but I’ve never seen a project fail because it contained too many comments.

JBGE, REDUX

JBGE is mostly applied to code documentation and comments, but you could apply the same rule to any kind of documentation. For example, you could write barely enough documentation to explain the requirements. That’s probably an even bigger mistake than skimping on code comments.

Documentation helps keep the whole project team working toward the same goals. If you don’t spell things out unambiguously, developers will start working at cross-purposes. At best you’ll lose a lot of time arguing about what the requirements mean. At worst you’ll face a civil war that will destroy your team.

As is the case with code documentation and comments, you don’t need to turn the requirements into a 1,200-page novel. However, if the requirements are ambiguous or confusing, pull out your thesaurus and clarify them.

JBGE is okay as long as you make sure your documentation actually is GE.

You can extend the JBGE idea even further and create designs that are just barely good enough, write code that’s just barely good enough, and perform tests that are just barely good enough. I’m a big fan of avoiding unnecessary work, but if everything you do is just barely good enough, the result probably won’t be anywhere near good enough. (Not surprisingly, no one advocates that approach. The JBGE philosophy seems to be reserved only for code comments.)

Some programming languages provide a special kind of comment that is intended to be pulled out automatically and used in text documentation. For example, the following shows a snippet of C# code with XML comments:

The comment’s summary token explains the method’s purpose. The param tokens describe the method’s parameters. The Visual Studio development environment can automatically extract these comments into an XML file that you can then process to produce documentation. The result doesn’t explain how the code works, but if you do a good job writing the comments, it does explain the interface that the method displays to other pieces of code. (Visual Studio also uses these comments to provide help pop-ups called IntelliSense to other developers who call this code.)

As is the case when you write code documentation and other comments, you don’t need to constantly update this kind of information as you work on a method. Finish the method, test it, and then write the comments once.