1. Introduction
“Commenting is a royal pain in the posterior” - “Comments are for weenies” - “I can understand my
code quite well, thank you very much” - “Good code speaks for itself” - “No time for that, got to
get that code out of the door”. Admit it, you have said some thing along these lines at least once
during your coding career. Maybe you even now still are in this kind of frame of mind.
Negative attitudes towards commenting may have several reasons:
z Programmer's hubris
z Lazyness
z No time left for documentation due to deadline constraints
None of these is a good reason for not commenting source code properly. We will look at these
arguments, discuss them and take a look at good commenting practice and its benefits.
As SharpDevelop is intended to be an IDE for all languages supported by the .NET platform – and
others, if support is available – this text will not discuss language specific commenting issues.
Knowledge of all languages referred to is not necessary for the understanding of this paper.
2. The Case against Commenting
We now take a look at those negative opinions offered in making a case against commenting code.
2.1 Programmer's Hubris
A good programmer is always a programmer with something of a well developed ego. Nothing is
impossible, everything is easy to understand. So much for theory.
In practice, reality checks are in order from time to time. Do you understand all your code after not
looking at it for, say, a year? Is legacy code left to you to maintain always obvious at first look, or
even after a few weeks of scrutiny? Truth is, most of the time it will take a lot of time and effort to
understand undocumented code, even if the code has not been obfuscated intentionally.
As an example, let us consider the solitaire encryption algorithm of Bruce Schneier in its 'concise'
version as published in Neal Stephensons novel 'Cryptonomicon'. It is implemented in Perl without
'spaghetti code', yet due to its terse coding style, it is almost incomprehensible, should you attempt
to figure out what it does:
Exhibit A:
#!/usr/bin/perl -s
## Ian Goldberg <ian@cypherpunks.ca>, 19980817
$f=$d?-1:1;4D=pack(C',33..86);$p=shift;
$p=~y/a-z/A-Z/;$U='$D=~s/.*)U$/U$1/;
$D=~s/U(.)/$1U/;';($V=$U)=~s/U/V/g;
$p=~s/[A_Z]/$k=ord($&)-64,&e/eg;$k=0;
while(<>){y/a-z/A-Z/;y/A-Z//dc;$o.=$_}$o='X'
while length($o)%5&&!$d;
$o=~s/./chr(($f*&e+ord($&)-13)%26+65/eg;
$o=~s/X*$//if $d;$o=~~s/.{5}/$& /g;
print”$o/n”;sub v{$v=ord(substr($D,$_[0]))-32;
$v>53?53:$v}
sub w{$D=~s/(.{$_[0]})(.*)(.)/$2$1$3/}
sub e{eval”$U$V$V”;$D=~s/(.*)([UV].*[UV])(.*]/$3$2$1/;
&w(&v(53));$k?(&w($k)):($c=&v(&v(0)),$c>52?&e:$c)}
© Bernhard Spuida 2002 3
评论0
最新资源