Skip to main content
deleted 12 characters in body
Source Link

Think about comments as one possible form of documentation. Arguably, they're the preferred form because they're immediately accessible when you're looking at the code. Some developers say code should be self-documenting, but I contend that self-documenting code is impossible. To understand why, ponder this:

Without documentation, there can be no such thing as a bug, because there is nothing to define correct behavior.

Sometimes the correct behavior isn't formally documented. Often it's just an assumption. If you encounter a method named Multiply that performs subtraction, it's pretty safe to assume that something is wrong. But if there's no documentation, you're going to have to dig through the program to determine whether you should rename the method or change what it does. If the only documentation is the method name, and some callers are assuming it does what it says, but others are using it based on what it actually does, where's the bug? If there were any documentation at all, even a comment, you could say authoritatively what the intent was and which code needs to be changed. Now imagine what this process would look like with a far less obvious and contrived example.

If there's no documentation, all behavior is based on assumptions. Sure, a method name can be documentation, if it fully describes everything the method does, every precondition, every postcondition, and side effect. Not very likely! When you're writing new code, be conscious of the assumptions you're making about what constitutes correct behavior. Try to imagine how obvious those assumptions are going to be to the person who reads it. If there's any doubt, write a comment.

Think about comments as one possible form of documentation. Arguably, they're the preferred form because they're immediately accessible when you're looking at the code. Some developers say code should be self-documenting, but I contend that self-documenting code is impossible. To understand why, ponder this:

Without documentation, there can be no such thing as a bug, because there is nothing to define correct behavior.

Sometimes the correct behavior isn't formally documented. Often it's just an assumption. If you encounter a method named Multiply that performs subtraction, it's pretty safe to assume that something is wrong. But if there's no documentation, you're going to have to dig through the program to determine whether you should rename the method or change what it does. If the only documentation is the method name, and some callers are assuming it does what it says, but others are using it based on what it actually does, where's the bug? If there were any documentation at all, even a comment, you could say authoritatively what the intent was and which code needs to be changed. Now imagine what this process would look like with a far less obvious and contrived example.

If there's no documentation, all behavior is based on assumptions. Sure, a method name can be documentation, if it fully describes everything the method does, every precondition, every postcondition. Not very likely! When you're writing new code, be conscious of the assumptions you're making about what constitutes correct behavior. Try to imagine how obvious those assumptions are going to be to the person who reads it. If there's any doubt, write a comment.

Think about comments as one possible form of documentation. Arguably, they're the preferred form because they're immediately accessible when you're looking at the code. Some developers say code should be self-documenting, but I contend that self-documenting code is impossible. To understand why, ponder this:

Without documentation, there can be no such thing as a bug, because there is nothing to define correct behavior.

Sometimes the correct behavior isn't formally documented. Often it's just an assumption. If you encounter a method named Multiply that performs subtraction, it's pretty safe to assume that something is wrong. But if there's no documentation, you're going to have to dig through the program to determine whether you should rename the method or change what it does. If the only documentation is the method name, and some callers are assuming it does what it says, but others are using it based on what it actually does, where's the bug? If there were any documentation at all, even a comment, you could say authoritatively what the intent was and which code needs to be changed. Now imagine what this process would look like with a far less obvious and contrived example.

If there's no documentation, all behavior is based on assumptions. Sure, a method name can be documentation, if it fully describes every precondition, postcondition, and side effect. Not very likely! When you're writing new code, be conscious of the assumptions you're making about what constitutes correct behavior. Try to imagine how obvious those assumptions are going to be to the person who reads it. If there's any doubt, write a comment.

Source Link

Think about comments as one possible form of documentation. Arguably, they're the preferred form because they're immediately accessible when you're looking at the code. Some developers say code should be self-documenting, but I contend that self-documenting code is impossible. To understand why, ponder this:

Without documentation, there can be no such thing as a bug, because there is nothing to define correct behavior.

Sometimes the correct behavior isn't formally documented. Often it's just an assumption. If you encounter a method named Multiply that performs subtraction, it's pretty safe to assume that something is wrong. But if there's no documentation, you're going to have to dig through the program to determine whether you should rename the method or change what it does. If the only documentation is the method name, and some callers are assuming it does what it says, but others are using it based on what it actually does, where's the bug? If there were any documentation at all, even a comment, you could say authoritatively what the intent was and which code needs to be changed. Now imagine what this process would look like with a far less obvious and contrived example.

If there's no documentation, all behavior is based on assumptions. Sure, a method name can be documentation, if it fully describes everything the method does, every precondition, every postcondition. Not very likely! When you're writing new code, be conscious of the assumptions you're making about what constitutes correct behavior. Try to imagine how obvious those assumptions are going to be to the person who reads it. If there's any doubt, write a comment.