Well curious as i am i looked for it and i must admit you are right
it is clearly stating that old code should be removed ,,,,,
hmm i am learning every day something new
from now on i will remove that dead code
and will replace it with a
brief explanation of what the new code does
Comments
Software documentation exists in two forms, external and internal. External
documentation is maintained outside of the source code, such as
specifications, help files, and design documents. Internal documentation is
composed of comments that developers write within the source code at
development time.
One of the challenges of software documentation is ensuring that the
comments are maintained and updated in parallel with the source code.
Although properly commenting source code serves no purpose at run time, it
is invaluable to a developer who must maintain a particularly intricate or
cumbersome piece of software.
Following are recommended commenting techniques:
a.. When modifying code, always keep the commenting around it up to date.
b.. At the beginning of every routine, it is helpful to provide standard,
boilerplate comments, indicating the routine's purpose, assumptions, and
limitations. A boilerplate comment should be a brief introduction to
understand why the routine exists and what it can do.
c.. Avoid adding comments at the end of a line of code; end-line comments
make code more difficult to read. However, end-line comments are appropriate
when annotating variable declarations. In this case, align all end-line
comments at a common tab stop.
d.. Avoid using clutter comments, such as an entire line of asterisks.
Instead, use white space to separate comments from code.
e.. Avoid surrounding a block comment with a typographical frame. It may
look attractive, but it is difficult to maintain.
f.. Prior to deployment, remove all temporary or extraneous comments to
avoid confusion during future maintenance work.
g.. If you need comments to explain a complex section of code, examine the
code to determine if you should rewrite it. If at all possible, do not
document bad code-rewrite it. Although performance should not typically be
sacrificed to make the code simpler for human consumption, a balance must be
maintained between performance and maintainability.
h.. Use complete sentences when writing comments. Comments should clarify
the code, not add ambiguity.
i.. Comment as you code, because most likely there won't be time to do it
later. Also, should you get a chance to revisit code you've written, that
which is obvious today probably won't be obvious six weeks from now.
j.. Avoid the use of superfluous or inappropriate comments, such as
humorous sidebar remarks.
k.. Use comments to explain the intent of the code. They should not serve
as inline translations of the code.
l.. Comment anything that is not readily obvious in the code.
m.. To prevent recurring problems, always use comments on bug fixes and
work-around code, especially in a team environment.
n.. Use comments on code that consists of loops and logic branches. These
are key areas that will assist the reader when reading source code.
o.. Separate comments from comment delimiters with white space. Doing so
will make comments stand out and easier to locate when viewed without color
clues.
p.. Throughout the application, construct comments using a uniform style,
with consistent punctuation and structure.
Notes Despite the availability of external documentation, source code
listings should be able to stand on their own because hard-copy
documentation can be misplaced.
External documentation should consist of specifications, design documents,
change requests, bug history, and the coding standard that was used.
