There's two types of code documentation: documenting the interface, and documenting the code itself. One is for people who use your functions, one is for people who maintain your functions.
When documenting an interface of published functions, classes, and methods, you're...
- explaining what it's for
- explaining how to use it
- making promises about its behavior
- pointing out any caveats
- saving the user a lot of time
That last one is about scale. While you're learning, you're probably working on maybe a few hundred lines of code. A typical project is tens of thousands or hundreds of thousands of lines which relies on millions and millions of lines of dependent code. Programmers have better things to do than read every line of code they rely on, and it's simply impossible now.
For example, here's my documentation for a function which centers strings. It is written in perldoc, Perl's standard documentation language. It can then be rendered in a variety of formats, here it is in HTML. Most modern languages have a standard way of embedding documentation in the code (C does not, it is 50 years old).
=head3 center
my $centered_string = $string->center($length);
my $centered_string = $string->center($length, $character);
Centers $string between $character. $centered_string will be of
length $length.
C<$character> defaults to " ".
say "Hello"->center(10); # " Hello ";
say "Hello"->center(10, '-'); # "---Hello--";
C<center()> will never truncate C<$string>. If $length is less
than C<< $string->length >> it will just return C<$string>.
say "Hello"->center(4); # "Hello";
It contains examples of use, an explanation of what the function does, and a caveat about what happens if the length is shorter than the string.
Code which calls center will be relying on it behaving consistently. Without the documentation, they'd have to guess what it did based on reading the code. This can lead to misunderstanding its purpose, and it can also lead to relying on implementation details which may change in the future. By writing documentation you make a contract with the user that this is how you promise the function will always behave this way, and the user will only rely on the documented features. With this contract in hand, you are free to change the implementation without worrying that you're going to break someone else's code ("backwards compatibility"), and the user is free to use the function without worrying center will change and break their code.
Ideally, the users of your functions never have to look at the code at all; the documentation explains everything.
When documenting the code itself, you generally don't document what the code is doing, but why it is doing it. The why is not always obvious; that knowledge only lives in somebody's head (and maybe a commit log message). You cannot rely on being able to speak with the author, they might not be available, and that does not scale.
For example, the comment here explains the bulk of this function is working around a bug in another library. And it's also faster.
sub _get_datetime_timezone {
state $local_tzfile = "/etc/localtime";
# Always be sure to honor the TZ environment var
return "local" if $ENV{TZ};
# Work around a bug in DateTime::TimeZone on FreeBSD where it
# can't determine the time zone if /etc/localtime is not a link.
# Tzfile is also faster to do localtime calculations.
if( -e $local_tzfile ) {
# Could go through more effort to figure it out. Meh.
my $tzname = "Local";
if( -l $local_tzfile ) {
if( my $real_tzfile = eval { readlink $local_tzfile } ) {
$tzname = $real_tzfile;
}
}
require DateTime::TimeZone::Tzfile;
my $tz = DateTime::TimeZone::Tzfile->new(
name => $tzname,
filename => $local_tzfile
);
return $tz if $tz;
}
return "local";
}
Without that comment, every reader would have to puzzle it out for themselves wasting time, maybe getting it wrong. Maybe even concluding the code isn't necessary and deleting it reopening an old bug.
Sometimes you do comment on what the code is doing if it is not immediately obvious. For example... (this is Perl).
time => sub {
my ($class, $caller) = @_;
require perl5i::2::DateTime;
# Export our gmtime() and localtime() and time()
(\&perl5i::2::DateTime::dt_gmtime)->alias($caller, 'gmtime');
(\&perl5i::2::DateTime::dt_localtime)->alias($caller, 'localtime');
(\&perl5i::2::DateTime::dt_time)->alias($caller, 'time');
},
(\&perl5i::2::DateTime::dt_gmtime)->alias($caller, 'gmtime'); is a mouthful, even for Perl. The comment explains what this code is doing.
However, comments have a way of falling out of date and becoming wrong. It's better to rework the code so it can be plainly understood. Perhaps by writing a wrapper function that reads more clear.
time => sub {
my ($class, $caller) = @_;
require perl5i::2::DateTime;
alias(\&perl5i::2::DateTime::dt_gmtime, as => 'gmtime', in => $caller);
alias(\&perl5i::2::DateTime::dt_localtime, as => 'localtime', in => $caller);
alias(\&perl5i::2::DateTime::dt_time, as => 'time', in => $caller);
},
To a Perl programmer that means it's making the function perl5i::2::DateTime::dt_time available as the function time in the namespace $caller. And they can look up the details in the documentation for alias.
